Macaulay2 for Debian
====================

Javascript libraries
--------------------
Macaulay2 uses a number of Javascript libraries.  In particular, they
are used to render mathematical expressions in the browser-based
documentation and to visualize various mathematical objects by the
Visualize package.

Upstream embeds these libraries in the source code, often minimized.
This is not desirable for the Debian package.  For the libraries that
are already available in Debian, we repack the tarball (using
Files-Excluded in debian/copyright) without the embedded copies and
use dh_linktree to create symbolic links to the Debian versions.

There are three libraries that are not yet available in Debian, and so
the embedded copies remain.  In particular:

* BootSideMenu (ITP #960097).  Macaulay2 ships the full source code.

* noUiSlider (ITP #960618).  Macaulay2 ships minified source, so we
  include the full source code in debian/missing-sources, obtained
  from https://github.com/leongersen/noUiSlider/tree/8.5.1.

* The render-a11y-string KaTeX extension. It was added in KaTeX
  version 0.11.0, but only 0.10.2 is currently available in Debian.
  Macaulay2 ships minified source, so we include the full source code
  in debian/missing-sources, obtained from
  https://github.com/KaTeX/KaTeX/tree/v0.12.0.

dwww
----
The Macaulay2 documentation is registered with doc-base.  In order to
view the html documentation properly in your web browser using dwww,
you must append "/usr/share/Macaulay2" to DWWW_DOCPATH in
/etc/dwww/dwww.conf.  Otherwise, some resources (e.g., CSS and
Javascript files) will be unavailable.

Suggested packages
------------------
Quite a few additional Debian packages will be installed alongside
Macaulay2 automatically due to being listed in "Depends" or
"Recommended", but there are a number of others that are listed under
"Suggests" that will not be installed unless you pass
"--install-suggests" to apt or install them separately.  They are:

* dot2tex - Used by showTikZ function in Graphs package.

* fig2dev - Used by gfanRender and gfanRenderStaircase functions in
  gfanInterface package.

* graphviz - Used by displayGraph function in Graphs package.

* imagemagick - Used by displayGraph function in Graphs package.
  However, any image viewer will do -- set the "JpgViewer" configuration
  option when loading the package to change the viewer.

* pdf-viewer (virtual package) - Used by displayPoset function in
  Posets package.  The default pdf viewer is called using xdg-open;
  use xdg-mime to change it.  Alternatively, set the "DefaultPDFViewer"
  configuration option when loading the package.

* polymake - Used by Polymake, StatePolytope, and Tropical packages.

* sdpa - Used by SemidefiniteProgramming package.

 -- Doug Torrance <dtorrance@piedmont.edu>, Fri,  1 Jan 2021 17:17:56 -0500
