.. _xmlmind:

===================================
 Usage of XMLmind XML Editor (XXE)
===================================

Introduction
============

Some background reading: https://www.xml.com/pub/a/2007/06/20/getting-productive-with-xmlmind.html

See https://wiki.edition-open-access.de/doku.php?id=metopesinstallationmac and following pages in the wiki for setup and tweaks.

The XXE version used here is pretty old, and updates for métopes are under development. It might make sense to get in touch with the developers (see http://www.metopes.fr/metopes-contact.html) to check for updates.

Although the strength of the editor lies in hiding the real XML there is the possibility to open a proper XML editor where you can actually edit all of the code. Select `View` -> `15 XML Source` to do that.

Extending with scripts
======================

See https://wiki.edition-open-access.de/doku.php?id=xmltopdf#export_parameters for getting a general idea how to set parameters for XSL transformations.

The XSL script is part of EOASkripts and is manually updated in the ``eoa-xmlmind`` repository.

Adding a parameter
------------------

A new parameter was added to the XSL script: https://github.molgen.mpg.de/EditionOpenAccess/EOASkripts/commit/da7d234d47a47d521c8a8c5f0b7e46fb802052e8

The new parameter needs to be added in the ``.incl`` file: https://github.molgen.mpg.de/EditionOpenAccess/eoa-xmlmind/commit/d626dcc0561096fa7757a708672015c5565ce53a so that it is available in the export window. To make it appear there, close all buffers in XXE and select ``Options -> Reload All Configurations``. Or restart the whole program.


LaTeX export
============

The XML document can be exported at any time to LaTeX and typeset. See https://wiki.edition-open-access.de/doku.php?id=xmltopdf for a more detailed description.

.. image:: /_static/xxe_runlatex.png
   :scale: 50 %
   :alt: xxe running latex info
   :align: center

.. note::
   Currently, the exporter is not capable of generating indices for books (for background, see https://github.molgen.mpg.de/EditionOpenAccess/eoa-xmlmind/issues/3). It will generate a warning, depicted below. If you click ``OK``, the following scripts will run, but an index will not have been typeset. Use the command line or a TeX editor to do additional runs of XeLaTeX to generate the index.

.. image:: /_static/xxemakeindexwarning.png
   :scale: 50 %
   :alt: makeindex warning
   :align: center

Hyphenation
-----------

Put LaTeX-like hyphenation patterns into a file called ``hyphenation.tex`` and store it in the ``texfiles`` directory. When exporting, set the ``hyphenation`` parameter to ``true``.

Manual settings
---------------

At some point, book parts like the frontmatter and list of contributors might contain pieces that can not be handled easily by the exporter, because of customizations. To store these and to have the possibility to manually perform changes, make a LaTeX export of the project and copy the file ``frontmatter.tex`` (which should be in ``output/latex/texfiles/``) to ``texfiles/frontmatter-manual.tex`` in the root directory. The name (including case and hyphen) has to be like this! When exporting, set the ``frontmattermanual`` parameter to ``true``.

The same goes for a list of contributors:
  - set ``contributors`` to ``true`` in the export settings
  - copy ``output/latex/texfiles/contributors.tex`` to ``texfiles/contributors-manual.tex``
  - edit the file to your liking
  - in addition to ``contributors``, do also set ``contributorsmanual`` to ``true`` in the export settings
  - proceed as usual

.. note::

   Be aware though, that changes you now make in the ``XML`` file will not show up in the manually edited files: e. g. changes of names, affilitations, the license of the publication, distributor. These things have to be checked thoroughly before publication.