summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/webquiz/README.rst
blob: 60d0f52181f1c6db3a3aa9f0a6379fe6eafb53e4 (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
====================================================
WebQuiz: a LaTeX_ package for writing online quizzes
====================================================

WebQuiz_ makes it possible to use LaTeX_ to write interactive online quizzes.
The quizzes are first written in LaTeX_ and then converted into HTML using
WebQuiz_, which is written in python. The conversion from LaTeX_ to HTML is
done behind the scenes using TeX4ht_. The idea is that you should be able to
produce nice online quizzes using WebQuiz_ and basic knowledge of LaTeX_.

WebQuiz_ is designed to be used from the command-line.  For example, if
`quiz1.tex` is a LaTeX file for a quiz then:

:`latex quiz1`:
    produces a "readable" DVI file for the quiz
:`pdflatex quiz1`:
    produces a "readable" PDF file for the quiz
:`webquiz quiz1`:
    creates the web page `quiz1.html`

If you prefer to use LaTeX_ from a GUI for LaTeX_ then it should be possible to
configure it to use WebQuiz_ directly. As an example, the manual provides some
details about how to do this for TeXShop.

Usage
-----

usage: webquiz [-h] [-q] [-d] [-s] [--latex | -l | -x] [-r RCFILE]
               [-i | -e | --settings [SETTINGS]]
               [quiz_file [quiz_file ...]]

A LaTeX package for writing online quizzes

positional arguments:
  quiz_file             latex quiz files

optional arguments:
  -h, --help            show this help message and exit
  -q, --quiet           Suppress tex4ht messages (also -qq etc)
  -d, --draft           Use make4ht draft mode
  -s, --shell-escape    Shell escape for tex4ht/make4ht
  --latex               Use latex to compile document with make4ht (default)
  -l, --lua             Use lualatex to compile the quiz
  -x, --xelatex         Use xelatex to compile the quiz
  -r RCFILE, --rcfile RCFILE
                        Specify location of the webquiz rc-file
  -i, --initialise      Install web components of webquiz
  -e, --edit-settings   Edit default settings for webquiz
  --settings <SETTINGS>
                        List default settings for webquiz

Installation
------------
To use WebQuiz_ you need to have a standard LaTeX_ distribution installed, such as TeXLive_, that includes TeX4ht_. In addition, you need to have Python3_ installed. As WebQuiz_ uses scalable vector graphics (SVG) you should check that all of the dependencies of dvisvgm_ are installed on your system, especially if you plan on using graphics or images.

Once the TeX components of WebQuiz_ package have been installed you can install the web components of WebQuiz_ using the following command, which needs to be run  from the command line:

> webquiz --initialise

If you want to install the web components of WebQuiz_ into a system directory then you need to run this command from an administrators account, so using `sudo` on a unix-like system. For more details about the installation and configuration of WebQuiz_ please see Section 3.2 of the WebQuiz_ manual.

Please see the manual for more details about initialising and using WebQuiz_.

Installation from ctan
----------------------
If you are installing WebQuiz using the zip file from ctan, as opposed to
installing the package from TeX distribution like TeXLive, then the following
steps are recommended:

- Create a symbolic link, or equivalent, to the main WebQuiz executable, which
  is the file webquiz.py in the scripts directory
- Copy the latex directory to somewhere in TeX search path, or set your
  TEXINPUTS environment variable appropriately, and then run `mktexlsr` or
  equivalent so that LaTeX and WebQuiz can find these files.
- Ideally the doc subdirectory should be copied into the doc/layetx subdirecory
  of the main TeX distribution.

If you are using a unix system, or macosx, there is an (undocumented)
command-line option `--tex-install` that installs the three different
components of WebQuiz_ into the standard locations in the TeXLive
tree:

- $TEXMFMAIN/tex/latex/webquiz  all LaTeX files
- $TEXMFMAIN/scripts/webquiz    the python programs
- $TEXMFMAIN/doc/latex/webquiz  the documentation and web components
- A symbolic link is made from the TeX bin directory to the main
  WebQuiz executable $TEXMFMAIN/scripts/webquiz/webquiz.py

To install these files in TEXMFMAIN you will almost certainly need
adminsistrator or root privledges, so on a unix-like system you will
need to use:

> sudo webquiz/scripts/webquiz --tex-install

In principle, this command may also work on a windows computer,
provided that the command `kpsewhich` is available, but this is
untested.

Once the files above are in place initialise WebQuiz by following the
installation instructions above.

Mainly for development purposes, there is another undocumented
command-line option for removing these files from TEXMFMAIN:

> sudo webquiz/scripts/webquiz --tex-uninstall

System requirements
-------------------

In order to work WebQuiz needs the following programs to be installed on your
system:

* An up-to-date LaTeX_ distribution, such as that provided by TeXLive_. In
  particular, you need to have TeX4ht_ and make4ht_ installed.
  Unfortunately, since TeXLive 2018 was released there have been a significat
  bunber of updates to a number of packahges that WebQuiz_ uses, including
  updates to TeX4ht_, make4ht_, tikz_ and pstricks_. For this reason, *it is
  strongly recommended that you all packages from ctan_ before using WebQuiz_*.

* python3_ As of writing python 3.7.2 is available.

* Javascript_

* If you plan to use pstricks_ with WebQuiz_, or if you want to
  compile the online manual for WebQuiz, then you need to ensure that
  ghostscript_ and dvisvgm_ are installed and properly configured on your
  system. See the WebQuiz_ manual and the dvisvgm_ documentation for more
  details

* A web server. To view online quizzes you of course need a web server. As
  described in the **Installation** section you will also need to copy of the
  WebQuiz_ components onto your web server using the command:

  > webquiz --initialise

Authors
-------
The LaTeX component of WebQuiz_ was written by Andrew Mathas and the python, css and javascript code was written by Andrew Mathas (and Don Taylor), based on an initial protype of Don Taylor's from 2001. Since 2004 the program has been maintained and developed by Andrew Mathas. Although the program has changed substantially since 2004 Don's idea of using TeX 4ht, and some of his code, is still very much in use.

Copyright (C) 2004-2019

License
-------
GNU General Public License, Version 3, 29 June 2007

This program is free software: you can redistribute it and/or modify it
under the terms of the GNU\_General Public License
(GPL_) as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.

.. _GPL:         https://www.gnu.org/licenses/gpl-3.0.en.html
.. _LaTeX:       https://www.latex-project.org/
.. _Python3:     https://www.python.org
.. _TeX4ht:      http://www.tug.org/tex4ht/
.. _TeXLive:     https://www.tug.org/texlive/
.. _WebQuiz:     https://github.com/AndrewAtLarge/WebQuiz/
.. _ctan:        https://ctan.org/
.. _dvisvgm:     https://ctan.org/pkg/dvisvgm
.. _ghostscript: https://www.ghostscript.com
.. _javascript:  https://www.javascript.com
.. _make4ht:     https://ctan.org/pkg/make4ht
.. _pstricks:    https://ctan.org/pkg/pstricks
.. _tikz:        https://ctan.org/pkg/tikz