Known issues
============

Backref
-------

Sometimes an incompatibility arises when using the option `backref` in
`hyperref` and using `\\url` in bibliographical entries inside the
`\\begin{thebibliography}` environment; reformatting entries, (adding
`\\newblock`, adding an extra newline before `\\end{thebibliography}`
) may solve it.
For some unfathomable reason, this `bug` is not
triggered when `\\url` is used in bibliographical entries inside a
`.bib` file, later processed with `bibtex`.


Sqlite
------

Compiling LaTeX code is slow; so compilations of multiple versions of
LaTeX are run in parallel (using `forked` processes).
These processes eventually will access the database to update
metadata, all at the same moment (more or less), alas.
The `sqlite` database does not allow concurrency;
so sometimes the database subsystem will raise
an exception `Database is locked`, that is
reported to the user.

In this case there are some mitigations that may be applied:

- grow the `timeout` parameter in `settings`

- use `WAL` mode: https://sqlite.org/wal.html .

In the long run, though, using a better database may be the only real solution. Here
are some steps to convert a portal from `sqlite` to `MySQL`.

- Install MySQl and check that the root user can access it.

- Install  `mysqlclient`, by running::

  # pip install mysqlclient

- Stop your portal (`eg` stop Apache)

- **backup all your site data** in case some catastrophic error occours.

- run::

  # ${COLDOC_SRC_ROOT}/ColDocDjango/manage.py   dumpdata --exclude contenttypes  --exclude sessions --indent 2   -o dump-site.json

- run::

  # sudo mysql < ${COLDOC_SITE_ROOT}/mysql.sql

- edit ${COLDOC_SITE_ROOT}/settings.py, uncomment the line `exec(...)` that sets up the MySQL database parameters.

- run::

  # ${COLDOC_SRC_ROOT}/ColDocDjango/manage.py  migrate

- run::

  # ${COLDOC_SRC_ROOT}/ColDocDjango/manage.py  loaddata dump-site.json

- Start your portal (and cross fingers)