summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/webquiz/scripts/webquiz_makequiz.py
blob: 5f9e66f61bbe881f878b871ed354dac7e7843b37 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
#!/usr/bin/env python3
r'''
------------------------------------------------------------------------------
    webquiz_makequiz | build and generate the quiz page using webquiz_xml
                        | and webquiz_layout
------------------------------------------------------------------------------
    Copyright (C) Andrew Mathas, University of Sydney

    Distributed under the terms of the GNU General Public License (GPL)
                  http://www.gnu.org/licenses/

    This file is part of the WebQuiz system.

    <Andrew.Mathas@sydney.edu.au>
    <Donald.Taylor@sydney.edu.au>
------------------------------------------------------------------------------
'''
import subprocess
import codecs
import shutil
import os
import re

import webquiz_templates
import webquiz_util
import webquiz_xml

#################################################################################
class MakeWebQuiz(object):
    """
    Convert a webquiz latex file to an online quiz.

    There are several steps:
      1. If given a LaTeX file then run htlatex/make4ht on the latex file to generate an
         xml file for the quiz that has all LaTeS markup converted to html.
      2. Read in the xml file version of the quiz
      3. Spit out the html version

    The HTMl is constructed using the template strings in webquiz_templates
    """
    # attributes that will form part of the generated web page
    header         = ''  # page header: title, meta data, links
    css            = ''  # css specifications
    javascript     = ''  # javascript code
    quiz_questions = ''  # the main quiz page
    side_menu      = ''  # the left hand quiz menu

    def __init__(self, quiz_name, quiz_file, options, settings, metadata):
        self.options = options
        self.settings = settings
        self.metadata = metadata
        self.quiz_file, extension = os.path.splitext(quiz_file)
        self.quiz_name = os.path.basename(self.quiz_file)
        self.webquiz_url = settings['webquiz_url']
        if self.webquiz_url[-1] == '/':
            self.webquiz_url =  self.webquiz_url[:len(self.webquiz_url)-1]

        # run htlatex only if quiz_file has a .tex extension
        if extension == '.tex':
            self.htlatex_quiz_file()

        self.read_xml_file()

        # use kpsewhich to fine the webquiz language file
        try:
            language_file = webquiz_util.kpsewhich('webquiz-{}.lang'.format(self.quiz.language))
        except subprocess.CalledProcessError:
            self.webquiz_error(
                'kpsewhich is unable to find language file for "{}"'.format(self.quiz.language)
            )
        # read the language file and store as a dictonary
        self.language = webquiz_util.MetaData(language_file)

        # initialise number of quiz and discussion items
        self.number_discussions = len(self.quiz.discussion_list)
        self.number_questions = len(self.quiz.question_list)

        # build the different components of the quiz web page
        self.add_meta_data()
        self.add_question_javascript()
        self.add_side_menu()
        self.add_quiz_header_and_questions()
        self.add_breadcrumbs()

        # add the initialisation warning if webquiz has not been initialised
        if self.settings.initialise_warning != '':
            self.breadcrumbs = self.settings.initialise_warning + self.breadcrumbs

        # now write the quiz to the html file
        with codecs.open(self.quiz_name + '.html', 'w', encoding='utf8') as file:
            # write the quiz in the specified format
            file.write(self.options.write_web_page(self))

    def webquiz_debug(self, msg):
        r'''
            Customised debugging message for the makequiz module
        '''
        webquiz_util.webquiz_debug(self.settings.debugging, 'makequiz: '+msg)

    def webquiz_error(self, msg, err=None):
        r'''
            Customised eror message for the makequiz module
        '''
        webquiz_util.webquiz_error(self.settings.debugging, 'makequiz: '+msg, err)

    def add_breadcrumbs(self):
        r'''
        Build the breadcrumbs by appropriately parsing the magic crumbs
        '''
        self.breadcrumbs = ''
        if self.quiz.breadcrumbs != '':
            # build the bread crumbs
            crumbs = '\n  '
            for crumb in self.quiz.breadcrumbs.split('|'):
                crumb = crumb.strip()

                if crumb == 'breadcrumb':
                    crumbs += self.add_breadcrumb_line(self.quiz.breadcrumb, missing='breadcrumb')

                elif crumb == 'department':
                    crumbs += self.add_breadcrumb_line(
                        text=self.quiz.department,
                        url=self.quiz.department_url,
                        missing='department')

                elif crumb == 'institution':
                    crumbs += self.add_breadcrumb_line(
                        text=self.quiz.institution,
                        url=self.quiz.institution_url,
                        missing='institution')

                elif crumb == 'quizindex':
                    if self.quiz.quiz_index == []:
                        crumbs += webquiz_templates.breadcrumb_quizindex.format(
                            quizzes_url=self.quiz.quizzes_url,
                            **self.language)
                    else:
                        crumbs += self.add_breadcrumb_line('Quizzes')

                elif crumb == 'Title':
                    crumbs += self.add_breadcrumb_line(text = self.quiz.title, missing='title')

                elif crumb == 'title':
                    title = self.quiz.title
                    crumbs += self.add_breadcrumb_line(
                                  text = title[:title.index(':')] if ':' in title else title,
                                  missing='title'
                              )

                elif crumb == 'unitcode':
                    crumbs += self.add_breadcrumb_line(
                        text=self.quiz.unit_code,
                        url=self.quiz.unit_url,
                        missing='unit code')

                elif crumb == 'unitname':
                    crumbs += self.add_breadcrumb_line(
                        text=self.quiz.unit_name,
                        url=self.quiz.unit_url,
                        missing='unit name')

                elif crumb != '':
                    lastSpace = crumb.rfind(' ')
                    url = crumb[lastSpace:].strip()
                    if url[0] == '/' or url.lower()[:4] == 'http':
                        crumbs += self.add_breadcrumb_line(text=crumb[:lastSpace], url=url)
                    else:
                        crumbs += self.add_breadcrumb_line(crumb)

            self.breadcrumbs = webquiz_templates.breadcrumbs.format(crumbs=crumbs)

    def add_breadcrumb_line(self, text, url='', missing='??'):
        r'''
        Return a line to add the bread crumbs, with errors if necessary
        '''
        if url == '':
            return webquiz_templates.breadcrumb_line_text.format(
                        text=text if text != '' else '?? ' + missing)

        return webquiz_templates.breadcrumb_line_url.format(
                    url=url, text=text if text != '' else '?? ' + missing)

    def htlatex_quiz_file(self):
        r'''
        Process the file using htlatex/make4ht. This converts the quiz to an xml
        with markup specifying the different elements of the quiz page.
        '''
        # at the minimum we put a css file into a <quiz_name> subdirectory
        if not os.path.exists(self.quiz_name):
            os.makedirs(self.quiz_name)

        try:
            self.options.talk('Processing {}.tex with TeX4ht'.format(self.quiz_name))
            # there is a slightly torturous process to convert the engine
            # settings into a command line option that make4ht understands
            cmd = 'make4ht --utf8 --config webquiz.cfg {draft} {engine} {escape} {make4ht_options} {quiz_file}.tex'.format(
                draft='--mode draft' if self.options.draft else '',
                engine=self.settings.settings['engine']['values'][self.options.engine],
                escape='--shell-escape' if self.options.shell_escape else '',
                make4ht_options=self.options.make4ht_options,
                quiz_file=self.quiz_file
            )
            self.options.run(cmd)

            # move the css file into the quiz_file subdirectory
            if os.path.exists(self.quiz_file + '.css'):
                shutil.move(
                    self.quiz_file + '.css',
                    os.path.join(self.quiz_name, self.quiz_name + '.css'))

            # Now move any images that were created into the quiz_name
            # subdirectory and update the links in the html file As htlatex
            # generates an html file, we rename this as an xml file at the same
            # time - in the cfg file, \Preamable{ext=xml} should lead to an xml
            # file being created but this doesn't seem to work ??
            try:
                fix_img = re.compile(r'^(|.* )\b(data|src)="([-0-9a-zA-Z]*\.(?:png|svg))" (.*)$')
                with codecs.open(self.quiz_file + '.html', 'r', encoding='utf8') as make4ht_file:
                    with codecs.open(self.quiz_name + '.xml', 'w', encoding='utf8') as xml_file:
                        for line in make4ht_file:
                            match = fix_img.match(line)
                            if match is None:
                                xml_file.write(line)
                            else:
                                # update html link and move file
                                start, src, image, rest_of_line = match.groups()
                                xml_file.write(r'{}{}="{}/{}" {}'.format(
                                    start, src, self.quiz_name, image, rest_of_line))
                                shutil.move(image, os.path.join(self.quiz_name, image))

            except OSError as err:
                self.webquiz_error(
                    'there was a problem moving the image files for {}'.format(
                        self.quiz_name), err)

        except Exception as err:
            self.webquiz_error( 'something went wrong when running htlatex on {}'.format(self.quiz_file), err)

    def read_xml_file(self):
        r'''
        Read in the webquiz xml file for the quiz and store the xml document
        tree in ``self.quiz``.
        '''
        try:
            # read in the xml version of the quiz
            if not os.path.isfile(self.quiz_name + '.xml'):
                self.webquiz_error('{}.xml does not exist!?'.format(self.quiz_name))
            self.quiz = webquiz_xml.ReadWebQuizXmlFile(self.quiz_name + '.xml', self.settings)
        except Exception as err:
            self.webquiz_error('error reading the xml generated for {}. Please check your latex source.'
                .format(self.quiz_name), err)

    def add_meta_data(self):
        """ add the meta data for the web page to self.header """
        # meta tags`
        self.header += webquiz_templates.html_meta.format(
            version=self.metadata.version,
            authors=self.metadata.authors,
            webquiz_url=self.webquiz_url,
            description=self.metadata.description,
            copyright=self.metadata.copyright,
            department=self.quiz.department,
            institution=self.quiz.institution,
            quiz_file=self.quiz_name,
            theme=self.quiz.theme)
        if self.quiz.mathjs:
            self.header += webquiz_templates.mathjs

    def add_side_menu(self):
        """ construct the left hand quiz menu """
        if self.quiz.discussion_list != []:  # links for discussion items
            discussion_list = '\n       <ul>\n   {}\n       </ul>'.format(
                '\n   '.join(
                    webquiz_templates.discuss.format(b=q + 1, title=d.short_heading)
                    for (q, d) in enumerate(self.quiz.discussion_list)))
        else:
            discussion_list = ''

        # department and institution links
        department = '''<a href="{0.department_url}">{0.department}</a>'''.format(self.quiz)
        institution = '''<a href="{0.institution_url}">{0.institution}</a>'''.format(self.quiz)

        # question buttons
        if self.number_questions == 0:
            question_buttons = ''
        else:
            buttons = '\n' + '\n'.join(
                webquiz_templates.button.format(b=q,
                    cls='button-selected' if self.quiz.discussion_list==[] and q==1 else 'blank'
                )
                for q in range(1, self.number_questions + 1))
            question_buttons=webquiz_templates.question_buttons.format(
                buttons=buttons, **self.language
            )

        # the full side menu
        self.side_menu = webquiz_templates.side_menu.format(
            discussion_list=discussion_list,
            version=self.metadata.version,
            department=department,
            institution=institution,
            side_questions=self.language['questions'] if self.number_questions>0 else '',
            question_buttons=question_buttons,
            copyright_years=self.metadata.copyright[:self.metadata.copyright.index(' ')],
            **self.language)

    def add_question_javascript(self):
        """
        Add the javascript for the questions to self and write the javascript
        initialisation file, <quiz>/quiz_specs.js, for the quiz.  When the quiz
        page is loaded, WebQuizInit reads the quiz_specs initialisation file to
        load the answers to the questions,  and the headers for the discussion
        items. We don't explicitly list quiz_specs.js in the meta data for the
        quiz page because we want to hide this information from the student,
        although they can easily get this if they open by the javascript
        console and know what to look for.
        """

        try:
            os.makedirs(self.quiz_name, exist_ok=True)
            os.chmod(self.quiz_name, mode=0o755)
            with codecs.open(os.path.join(self.quiz_name, 'wq-' + self.quiz_name + '.js'), 'w',
                             encoding='utf8') as quiz_specs:
                if self.number_discussions > 0:
                    for (i, d) in enumerate(self.quiz.discussion_list):
                        quiz_specs.write('Discussion[{}]="{}";\n'.format(i+1, d.heading))
                if self.number_questions > 0:
                    for (i, question) in enumerate(self.quiz.question_list):
                        # QuizSpecifications is a 0-based array
                        quiz_specs.write('QuizSpecifications[{}]=[];\n'.format(i+1))
                        quiz_specs.write('QuizSpecifications[{}].type="{}";\n'.format(i+1, question.type))
                        if question.type == 'input':
                            quiz_specs.write('QuizSpecifications[{}].value="{}";\n'.format(i+1,
                                question.answer.lower() if question.comparison=='lowercase'
                                                        else question.answer
                              )
                            )
                            quiz_specs.write('QuizSpecifications[{}].comparison="{}";\n'.format(i+1, question.comparison))
                        else:
                            quiz_specs.write(''.join(
                                    'QuizSpecifications[{}][{}]={};\n'.format(i+1, j, s.correct)
                                    for (j, s) in enumerate(question.items)
                                )
                            )

                if self.quiz.hide_side_menu:
                    quiz_specs.write('toggle_side_menu();\n')
                if self.quiz.one_page:
                    quiz_specs.write('onePage = true;\n')
                if self.quiz.random_order:
                    quiz_specs.write('shuffleQuestions();\n')
                quiz_specs.write('initSession();\n')
                if self.number_discussions+self.number_questions>0:
                    quiz_specs.write('gotoQuestion({});'.format(
                        -1 if self.number_discussions>0 else 1)
                    )

        except Exception as err:
            self.webquiz_error('error writing quiz specifications', err)

        self.javascript = webquiz_templates.questions_javascript.format(
            webquiz_url=self.webquiz_url,
            mathjax=self.settings['mathjax']
        )
        self.webquiz_init = webquiz_templates.webquiz_init.format(
            number_questions=self.number_questions,
            number_discussions=self.number_discussions,
            quiz_file=self.quiz_name,
        )

    def add_quiz_header_and_questions(self):
        r'''
        Write the quiz head and the main body of the quiz.
        '''
        if self.quiz.one_page:
            arrows = ''
        else:
            arrows = webquiz_templates.navigation_arrows.format(
                        question_number=self.quiz.discussion_list[0].heading
                                    if self.quiz.discussion_list != []
                                    else '1' if self.quiz.question_list > []
                                    else '',
                        **self.language
                    )

        # specify the quiz header - this will be wrapped in <div class="question-header>...</div>
        self.quiz_header = webquiz_templates.quiz_header.format(
            title=self.quiz.title,
            arrows=arrows,
            **self.language
        )

        # index for quiz
        if self.quiz.quiz_index != []:
            # add index to the web page
            self.quiz_questions += webquiz_templates.quiz_index_div.format(
                title=self.quiz.title if self.quiz.title!='' else self.quiz.unit_name,
                quiz_index='\n          '.join(
                    webquiz_templates.index_item.format(
                        url=q.url,
                        title='{} {}. {}'.format(self.language['quiz'],num+1,q.title)
                                if q.prompt else q.title,
                    ) for (num, q) in enumerate(self.quiz.quiz_index)),
                **self.language)
            # write a javascript file for displaying the menu
            # quizmenu = the index file for the quizzes in this directory
            with codecs.open('quizindex.js', 'w', encoding='utf8') as quizmenu:
                quizmenu.write('var QuizTitles = [\n{titles}\n];\n'.format(
                    titles=',\n'.join("  ['{}', '{}']".format(
                             '{} {}. {}'.format(self.language['quiz'],num+1,q.title) 
                                       if q.prompt else q.title,
                              q.url)
                        for (num,q) in enumerate(self.quiz.quiz_index))
                    )
                )
                quizmenu.write(webquiz_templates.create_quizindex_menu)

        # now comes the main page text
        # discussion(s) masquerade as negative questions
        if self.quiz.discussion_list != []:
            dnum = 0
            for d in self.quiz.discussion_list:
                dnum += 1
                self.quiz_questions += webquiz_templates.discussion.format(
                    dnum=dnum,
                    discussion=d,
                    display='inline' if self.quiz.one_page else 'none',
                    heading=webquiz_templates.discussion_heading.format(d.heading)
                            if self.quiz.one_page else ''
                )

        # finally we print the questions
        if self.quiz.question_list != []:
            self.quiz_questions += ''.join(
                webquiz_templates.question_wrapper.format(
                    qnum=qnum + 1,
                    question_number='{} {}. '.format(self.language.question, qnum+1)
                                    if self.quiz.one_page else '',
                    display='inline' if self.quiz.one_page else 'none',
                    question=self.print_question(quiz_question, qnum + 1),
                    feedback=self.print_feedback(quiz_question, qnum + 1)
                )
                for (qnum, quiz_question) in enumerate(self.quiz.question_list))

    def print_question(self, question, qnum):
        r'''Here:
            - question is the question
            - qnum is the number of the question
        '''
        if question.type == 'input':
            self.webquiz_debug('Q{}: after_text={}.'.format(qnum, question.after_text))
            question_options = webquiz_templates.input_answer.format(
                                 size=5+len('{}'.format(question.answer)),
                                 after_text=question.after_text,
                                 qnum=qnum,
                                 answer=self.language['answer']+':' if question.prompt else ''
            )
        elif question.type in ['single', 'multiple']:
            question_options = webquiz_templates.choice_answer.format(
                    after_text=question.after_text,
                    choices='\n'.join(self.print_choices(qnum, question, choice)
                        for choice in range(len(question.items)))
            )
        else:
            self.webquiz_error('Unknown question type "{}" in question {}'.format(question.type, qnum))
        return webquiz_templates.question_text.format(
            qnum=qnum,
            question_text=question.text,
            nextquestion='' if self.quiz.one_page else webquiz_templates.nextquestion.format(**self.language),
            question_options=question_options,
            **self.language)

    def print_choices(self, qnum, question, part):
        r'''
        Here:
            - qnum     = question number
            - question = current question
            - part     = number of the option we need to process.
        We put the parts into question.columns multicolumn format, so we have
        to add '<tr>' and '</tr>' tags depending on part.
        '''
        choice = question.items[part]
        item = '<tr>' if question.columns == 1 or (part % question.columns) == 0 else '<td>&nbsp;</td>'
        if question.type == 'single':
            item += webquiz_templates.single_item.format(choice=choice.symbol, qnum=qnum, text=choice.text)
        elif question.type == 'multiple':
            item += webquiz_templates.multiple_item.format(
                choice=choice.symbol,
                qnum=qnum,
                optnum=part,
                text=choice.text
            )
        else:
            item += '<!-- internal error: %s -->\n' % question.type
            self.webquiz_error('Unknown question type "{}" in question {}'.format(question.type, qnum))

        if question.columns == 1 or (part+1) % question.columns == 0 or part == len(question.items) - 1:
            item += '   </tr><!-- part={}, cols={}, # answers = {} -->\n'.format(
                part, question.columns, len(question.items))
        return item

    def print_feedback(self, question, qnum):
        r'''
        Generate the HTML for displaying the feedback help text when the user
        answers a question.
        '''
        if question.type == 'input':
            feedback = webquiz_templates.tf_feedback_text.format(
                choice=qnum,
                feedback='true',
                correct_answer=self.language.correct,
                answer2='',
                text=question.feedback_right)
            feedback += webquiz_templates.tf_feedback_text.format(
                choice=qnum,
                feedback='false',
                correct_answer=self.language.incorrect,
                answer2=self.language.try_again,
                text=question.feedback_wrong)
        elif question.type == "single":
            feedback = '\n' + '\n'.join(
                webquiz_templates.single_feedback.format(
                    qnum=qnum,
                    part=snum + 1,
                    correct_answer=self.language.correct if s.correct == 'true' else self.language.incorrect,
                    alpha_choice=self.language.choice.format(s.symbol),
                    feedback=s.feedback,
                    **self.language)
                for (snum, s) in enumerate(question.items))
        elif question.type == "multiple":
            feedback = '\n' + '\n'.join(webquiz_templates.multiple_feedback.format(
                qnum=qnum,
                part=snum + 1,
                correct_answer=getattr(self.language, s.correct).capitalize(),
                feedback=s.feedback,
                multiple_choice_opener=self.language.multiple_incorrect.
                format(s.symbol),
                **self.language)
                for (snum, s) in enumerate(question.items)
            )
            feedback += webquiz_templates.multiple_feedback_correct.format(
                qnum=qnum,
                feedback='\n'.join(webquiz_templates.multiple_feedback_answer.format(
                                        correct_answer=getattr(self.language, s.correct).capitalize(),
                                        reason=s.feedback) for s in question.items),
                                    **self.language)
        else:
            self.webquiz_error('Unknown question type "{}" in question {}'.format(question.type, qnum))

        return '<div class="answer">' + feedback + '</div>'