UMCL
Universal Math Conversion Library
Contents
1. use the library in an application
2. develop input/output modules
3. UMCL Command line interface and tools
4. About the source code
5. Build instructions
5.1 Unix or cygwin
5.2 MS Windows Visual Studio
6. Credits
* - * - * - * - *
1. use the library in an application
====================================
To use the UMCL library, use the 'umcl.h' include file available in
the include directory.
The umcl.h file contains documentation about the functions. The
easiest way to start is to use the code of umcl_cli (see section 3)
which uses all the functions available in umcl. It can be used as ann
example.
UMCL is built against libxslt (which uses libxml2) and use extended
xslt (available in libexslt). Then it is necessary to have them
installed. Link your application using the following options:
-lumcl -lxml2 -lxslt -lexslt
temporary note: use also libiconv with the current version (-liconv)
this dependency should be remove in next release (when all tables will
be changed to unicode)
Note for windows users:
[ - The cygwin binary distrbution include all necessary cygwin
dlls. /unsupported at the moment]
- windows binaries for libxml2, libxslt, libexslt (together with
iconv and zlib to which they depend) are available at:
http://www.zlatkovic.com/libxml.en.html
2. develop input/output modules
===============================
To develop an output module, implement the functions present in
'umclo.h'. A simple way for modules based on an XSLT style sheet to
produce Braille output from MathML is to copy one of the existing
modules (BrailleNewFr for instance). Indeed a set of generic functions based
on libxslt were developped which make it very easy to create such a
module.
To develop an input module, implement the functions present in
'umcli.h'.
3. UMCL command line interface and tools
========================================
umcl_cli (UMCL command line interface) offers a command line interface
to all the functions of the library. Launch it without arguments to
have help. Exemples of use ar given below. All output are now encoded
in utf-8.
The tools directory contains a program (check_table) to check tbl
files (Braille tables). Launch it without arguments to have help.
Exemples of use of umcl_cli:
umcl_cli help
provides basic help
umcl_cli help commands
gives the list of existing commands
umcl_cli help convert
gives help about the 'convert' command.
"umcl_cli help <command>" gives help about a command
umcl_cli list modules
umcl_cli list tables
umcl_cli list all
respectively list modules, tables, and all modules and tables together.
umcl_cli info out BrailleFr
gives info about the module BrailleFr (especially the synonyms that
can be used with the convert command)
umcl_cli mathml2braille BrailleFr formule.xhtml
umcl_cli mathml2braille BrailleFrNew formule.xhtml
umcl_cli m2b BrailleFr formule.xhtml
umcl_cli m2b fr formule.xhtml
converts a formula from MathML to french Braille (various synonyms)
umcl_cli convert MathML BrailleFr formule.xhtml
umcl_cli convert mathml fr formule.xhtml
umcl_cli convert mml fr formule.xhtml
converts a formula from MathML to french Braille (various synonyms)
umcl_cli --tableout french-cbisf.tbl convert mml fr formule.xhtml
umcl_cli -to french-cbisf.tbl convert mml fr formule.xhtml
converts a formula from MathML to french Braille (various synonyms)
using the table french-cbisf.tbl for output
umcl_cli -to u28 convert mml fr formule.xhtml
converts a formula from MathML to french Braille (various synonyms)
using Braille unicodes characters for output
umcl_cli -to french-cbisf.tbl convert -o outfile mathml fr formule.xhtml
converts a formula from MathML to french Braille
using the table french-cbisf.tbl for output and saves output in outfile
instead of displaying result on stdout.
umcl_cli convert MathML MathML formule.xhtml
converts from MathML to Canonical MathML
umcl_cli -to german convert -o outfile cMathML BrailleFr formule.xhtml
umcl_cli -to german convert -o outfile cmml fr formule.xhtml
converts from Canonical MathML to French Braille using german
Braille table (if you are sure the input is canonical, then the processing
is much faster. It is useful when processig files that were put into
cmathml using the library and then stored in this format.
4. About the source code
========================
- the main module is in directory 'lib'
- input modules are in 'umcli'
- output modules are in 'umclo'
- command line interface is in 'umcl_cli'
- c headers files are in 'include'
- directory 'doc' is not very detailled for now but at least UMCL
Braille Table format is described. All documentation is in the
header files umcl.h, umcli.h and umclo.h
- directory 'data' contains all XML, XSLT, DTD and tables files
- sample contains sample files containing Mathml formulas. in the
directory mathml they are in MathML, in the directory cmathml they
are in Canonical MathML.
5. Build and install instructions
=================================
5.1 Unix or cygwin
The build system is made with autoconf, automake, autoheader and
libtool (necessary packages: autoconf, automake, libtool, make).
then you might need to do:
autoreconf -vif
./configure
make
sudo make install
(libxml2, libxslt and libexslt are necessary).
note: under linux libiconv is part of the std libc, no need to install
anything, but for windows and Mac OS X it is necessary to have
libiconv.
After install (the first time) it might be necessary to do:
sudo ldconfig
5.2 MS Windows Visual Studio
A VisualC6 project and a VisualC8 projects have been designed. They
are available on the project web resources (sourceforge.net). Download
one of them and unzip it inside the umcl directory (or umcl-x.y.z).
It is necessary to have some windows version of libxml,
libxslt and libexslt. The project is built to find those libraries in
../local/include and the lib files in ../local/lib. If they are not at
this place then it is necessary to modify the paths in the Visual C
project.
The libxml4umcl.zip file provides all this stuff. It is also possible
to donwload those library at the official place:
http://www.zlatkovic.com/libxml.en.html
6. Credits
==========
The Universal Maths Conversion Library (UMCL) was designed by
Dominique Archambault, University Pierre et Marie Curie-Paris 6,
Paris, France. Franck Guyon (UPMC-Paris 6) took part to the UMCL
development. The structure of the library was inspired from stuff
written for libbraille by Sebastien Sable for UPMC/Inova in the
Framework of the TiM project.
Independent modules are developed by various members of the iGuma
(International Group for Universal Maths Access).
See file AUTHORS for more details
This program comes with ABSOLUTELY NO WARRANTY.
This is free software, placed under the terms of the GNU Lesser
Library General Public License, as published by the Free Software
Foundation. Please see the files COPYING and COPYING.LESSER for
details.
