add troubleshooting instructions to fix animation issues related to

"show animations" or "reduced motion" in Windows and MacOS.

add troubleshooting instructions to fix animation issues related to
"show animations" or "reduced motion" in Windows and MacOS.
Miguel Barão
1 parent 91d0281a
Showing 1 changed file with 35 additions and 20 deletions Show diff stats
README.md
@@ -33,7 +33,7 @@ sudo port install python37 npm6              # MacOS
 ```
  
 #### Installing from source
-     
+
 Make sure that the build tools and libraries are installed:
  
 ```sh
@@ -54,7 +54,7 @@ This will install python locally under `~/.local/bin`. Make sure to add it to yo
  
 ### Install pip
  
-Python usually includes pip which is accessible through `python -m pip install something`, but it's also convenient to have the `pip` command directly available in the terminal. 
+Python usually includes pip which is accessible through `python -m pip install something`, but it's also convenient to have the `pip` command directly available in the terminal.
 To install `pip` from the system package manager:
  
 ```sh
@@ -70,12 +70,12 @@ python3.7 -m pip install pip        # install in user area
 ```
  
 The latter will install `pip` in your user account under `~/.local/bin`.
-In the end you should be able to run `pip --version` and 
+In the end you should be able to run `pip --version` and
 `python3 -c "import sqlite3"` without errors.
-Sometimes the `pip` command is named `pip3`, 
+Sometimes the `pip` command is named `pip3`,
 `pip3.7` or `pip-3.7`.
  
-Edit the configuration file `~/.config/pip/pip.conf` (FreeBSD, Linux) or 
+Edit the configuration file `~/.config/pip/pip.conf` (FreeBSD, Linux) or
 `Library/Application Support/pip/pip.conf` (MacOS) and add the lines
  
 ```ini
@@ -121,7 +121,7 @@ aprendizations --help
  
 We need certificates for https. Certificates can be self-signed or validated by a trusted authority.
  
-Self-signed can be used locally for development and testing, but browsers will 
+Self-signed can be used locally for development and testing, but browsers will
 complain. LetsEncrypt issues trusted and free certificates, but the server must have a registered publicly accessible domain name.
  
 #### Generating selfsigned certificates
@@ -141,7 +141,7 @@ sudo pkg install py36-certbot       # FreeBSD
 sudo apt install certbot            # Ubuntu
 ```
  
-To generate or renew the certificates, ports 80 and 443 have to be accessible. **The firewall and webserver have to be stopped**. 
+To generate or renew the certificates, ports 80 and 443 have to be accessible. **The firewall and webserver have to be stopped**.
  
 ```sh
 sudo certbot certonly --standalone -d www.example.com   # first time
@@ -163,7 +163,7 @@ chmod 400 cert.pem privkey.pem
 ### Database
  
 User data is maintained in a sqlite3 database which has to be created manually using the `initdb-aprendizations` command.
-The database file should be located in the same directory as the main 
+The database file should be located in the same directory as the main
 YAML configuration file.
  
 For example, to run the included demo do:
@@ -190,16 +190,16 @@ cd demo
 aprendizations demo.yaml
 ```
  
-Open the browser at [https://127.0.0.1:8443](https://127.0.0.1:8443). 
-If everything looks good, check at the correct address 
+Open the browser at [https://127.0.0.1:8443](https://127.0.0.1:8443).
+If everything looks good, check at the correct address
 `https://www.example.com:8443`.
-The option `--debug` provides more verbose logging and might 
+The option `--debug` provides more verbose logging and might
 be useful during testing.
  
 ### Firewall configuration
  
-Ports 80 and 443 are only usable by root. For security reasons the server runs as an unprivileged user on port 8443 for https. 
-To access the server in the default https port (443), port forwarding can be configured in the firewall. 
+Ports 80 and 443 are only usable by root. For security reasons the server runs as an unprivileged user on port 8443 for https.
+To access the server in the default https port (443), port forwarding can be configured in the firewall.
  
 #### FreeBSD and pf
  
@@ -254,20 +254,20 @@ pip install -U .        # updates installed version to latest
  
 ## Troubleshooting
  
-To help with troubleshooting, use the option `--debug` when running the server. 
-This will increase logs in the terminal and will present the python exception 
+To help with troubleshooting, use the option `--debug` when running the server.
+This will increase logs in the terminal and will present the python exception
 errors in the browser.
  
-Logging levels can be adjusted in `~/.config/aprendizations/logger.yaml` and 
+Logging levels can be adjusted in `~/.config/aprendizations/logger.yaml` and
 `~/.config/aprendizations/logger-debug.yaml`.
  
 If these files do not yet exist, there are examples in `aprendizations/config` that can be copied to `~/.config/aprendizations`.
  
 #### UnicodeEncodeError
  
-The server should not generate this error, but when using external scripts to 
-generate questions or to correct, these scripts can print unicode strings to 
-stdout. If the terminal does not support unicode, python will generate this 
+The server should not generate this error, but when using external scripts to
+generate questions or to correct, these scripts can print unicode strings to
+stdout. If the terminal does not support unicode, python will generate this
 exception.
  
 - FreeBSD fix: edit `~/.login_conf` to use UTF-8, for example:
@@ -280,6 +280,22 @@ me:\
  
 - Debian fix: check `locale`...
  
+
+#### The application runs but questions do not show up
+
+Some operating systems have an option to disable animations to try to avoid
+motion sickness in some people. Browsers will check this option with the OS and
+prevent animate.css library to work. Since questions have several animations,
+these will will not work and nothing is shown on the page.
+
+To fix this issue you need to allow animations in the Operating System:
+
+- On windows 10, go to System Preferences, search for "Show animations in
+  windows" and turn it **ON**.
+- On MacOS or iOS search for reduced motion and switch it **OFF**
+  (Preferences -> Acessibility -> Display -> Reduce motion).
+
+
 ## FAQ
  
 Common database manipulations:
@@ -301,4 +317,3 @@ sqlite3 students.db &quot;select student_id, count(topic_id) from studenttopic group 
 # Which questions have more wrong answers?
 sqlite3 students.db "select count(ref), ref from answers where grade<1.0 group by ref order by count(ref) desc"
 ```
-
...	...	@@ -33,7 +33,7 @@ sudo port install python37 npm6 # MacOS
33	33	```
34	34
35	35	#### Installing from source
36		-
	36	+
37	37	Make sure that the build tools and libraries are installed:
38	38
39	39	```sh
...	...	@@ -54,7 +54,7 @@ This will install python locally under `~/.local/bin`. Make sure to add it to yo
54	54
55	55	### Install pip
56	56
57		-Python usually includes pip which is accessible through `python -m pip install something`, but it's also convenient to have the `pip` command directly available in the terminal.
	57	+Python usually includes pip which is accessible through `python -m pip install something`, but it's also convenient to have the `pip` command directly available in the terminal.
58	58	To install `pip` from the system package manager:
59	59
60	60	```sh
...	...	@@ -70,12 +70,12 @@ python3.7 -m pip install pip # install in user area
70	70	```
71	71
72	72	The latter will install `pip` in your user account under `~/.local/bin`.
73		-In the end you should be able to run `pip --version` and
	73	+In the end you should be able to run `pip --version` and
74	74	`python3 -c "import sqlite3"` without errors.
75		-Sometimes the `pip` command is named `pip3`,
	75	+Sometimes the `pip` command is named `pip3`,
76	76	`pip3.7` or `pip-3.7`.
77	77
78		-Edit the configuration file `~/.config/pip/pip.conf` (FreeBSD, Linux) or
	78	+Edit the configuration file `~/.config/pip/pip.conf` (FreeBSD, Linux) or
79	79	`Library/Application Support/pip/pip.conf` (MacOS) and add the lines
80	80
81	81	```ini
...	...	@@ -121,7 +121,7 @@ aprendizations --help
121	121
122	122	We need certificates for https. Certificates can be self-signed or validated by a trusted authority.
123	123
124		-Self-signed can be used locally for development and testing, but browsers will
	124	+Self-signed can be used locally for development and testing, but browsers will
125	125	complain. LetsEncrypt issues trusted and free certificates, but the server must have a registered publicly accessible domain name.
126	126
127	127	#### Generating selfsigned certificates
...	...	@@ -141,7 +141,7 @@ sudo pkg install py36-certbot # FreeBSD
141	141	sudo apt install certbot # Ubuntu
142	142	```
143	143
144		-To generate or renew the certificates, ports 80 and 443 have to be accessible. The firewall and webserver have to be stopped.
	144	+To generate or renew the certificates, ports 80 and 443 have to be accessible. The firewall and webserver have to be stopped.
145	145
146	146	```sh
147	147	sudo certbot certonly --standalone -d www.example.com # first time
...	...	@@ -163,7 +163,7 @@ chmod 400 cert.pem privkey.pem
163	163	### Database
164	164
165	165	User data is maintained in a sqlite3 database which has to be created manually using the `initdb-aprendizations` command.
166		-The database file should be located in the same directory as the main
	166	+The database file should be located in the same directory as the main
167	167	YAML configuration file.
168	168
169	169	For example, to run the included demo do:
...	...	@@ -190,16 +190,16 @@ cd demo
190	190	aprendizations demo.yaml
191	191	```
192	192
193		-Open the browser at [https://127.0.0.1:8443](https://127.0.0.1:8443).
194		-If everything looks good, check at the correct address
	193	+Open the browser at [https://127.0.0.1:8443](https://127.0.0.1:8443).
	194	+If everything looks good, check at the correct address
195	195	`https://www.example.com:8443`.
196		-The option `--debug` provides more verbose logging and might
	196	+The option `--debug` provides more verbose logging and might
197	197	be useful during testing.
198	198
199	199	### Firewall configuration
200	200
201		-Ports 80 and 443 are only usable by root. For security reasons the server runs as an unprivileged user on port 8443 for https.
202		-To access the server in the default https port (443), port forwarding can be configured in the firewall.
	201	+Ports 80 and 443 are only usable by root. For security reasons the server runs as an unprivileged user on port 8443 for https.
	202	+To access the server in the default https port (443), port forwarding can be configured in the firewall.
203	203
204	204	#### FreeBSD and pf
205	205
...	...	@@ -254,20 +254,20 @@ pip install -U . # updates installed version to latest
254	254
255	255	## Troubleshooting
256	256
257		-To help with troubleshooting, use the option `--debug` when running the server.
258		-This will increase logs in the terminal and will present the python exception
	257	+To help with troubleshooting, use the option `--debug` when running the server.
	258	+This will increase logs in the terminal and will present the python exception
259	259	errors in the browser.
260	260
261		-Logging levels can be adjusted in `~/.config/aprendizations/logger.yaml` and
	261	+Logging levels can be adjusted in `~/.config/aprendizations/logger.yaml` and
262	262	`~/.config/aprendizations/logger-debug.yaml`.
263	263
264	264	If these files do not yet exist, there are examples in `aprendizations/config` that can be copied to `~/.config/aprendizations`.
265	265
266	266	#### UnicodeEncodeError
267	267
268		-The server should not generate this error, but when using external scripts to
269		-generate questions or to correct, these scripts can print unicode strings to
270		-stdout. If the terminal does not support unicode, python will generate this
	268	+The server should not generate this error, but when using external scripts to
	269	+generate questions or to correct, these scripts can print unicode strings to
	270	+stdout. If the terminal does not support unicode, python will generate this
271	271	exception.
272	272
273	273	- FreeBSD fix: edit `~/.login_conf` to use UTF-8, for example:
...	...	@@ -280,6 +280,22 @@ me:\
280	280
281	281	- Debian fix: check `locale`...
282	282
	283	+
	284	+#### The application runs but questions do not show up
	285	+
	286	+Some operating systems have an option to disable animations to try to avoid
	287	+motion sickness in some people. Browsers will check this option with the OS and
	288	+prevent animate.css library to work. Since questions have several animations,
	289	+these will will not work and nothing is shown on the page.
	290	+
	291	+To fix this issue you need to allow animations in the Operating System:
	292	+
	293	+- On windows 10, go to System Preferences, search for "Show animations in
	294	+ windows" and turn it ON.
	295	+- On MacOS or iOS search for reduced motion and switch it OFF
	296	+ (Preferences -> Acessibility -> Display -> Reduce motion).
	297	+
	298	+
283	299	## FAQ
284	300
285	301	Common database manipulations:
...	...	@@ -301,4 +317,3 @@ sqlite3 students.db "select student_id, count(topic_id) from studenttopic group
301	317	# Which questions have more wrong answers?
302	318	sqlite3 students.db "select count(ref), ref from answers where grade<1.0 group by ref order by count(ref) desc"
303	319	```
304		-
...	...