Highlight installation instructions
-----------------------------------

Content
=======

1. Package structure
2. Dependencies
3. Basic installation
4. Known compiler issues
5. LaTeX unicode support
6. Lazy pointer issue under MacOS X
7. Static linking (to run highlight as service)
8. Known distribution issues


1. Package structure
=====================

root of highlight-x.x
|
|-- examples            # examples for highlight scripting
|   |-- web_plugins     # plugins for various web toolkits
|   |-- tcl             # TCL extension
|   `-- swig            # SWIG interface and sample code
|-- gui_files           # supporting files for the optional GUI
|   |-- ext             # file open filter configuration
|   `-- l10n            # GUI translations
|-- langDefs            # language definitions (*.lang)
|-- man                 # man page
|-- plugins             # Lua plugin scripts
|-- src                 # source code
|   |-- cli             # command line interface code
|   |-- core            # highlight core code (builds the library)
|   |   |-- astyle      # Artistic Style code
|   |   |-- Diliculum   # Diliculum code
|   |   `-- re          # Regex code
|   `-- gui-qt          # optional GUI code
|   `-- include         # Header files
|   |   |-- astyle      # Artistic Style headers
|   |   |-- Diliculum   # Diliculum headers
|   |   `-- re          # Regex headers
`-- themes              # color themes (*.theme)

AUTHORS                 # contributors of code and patches
ChangeLog               # list of changes
COPYING                 # license
Doxyfile                # Doxygen configuration
filetypes.conf          # file type extension configuration
highlight.desktop       # desktop integration of optional GUI
INSTALL                 # this file
makefile                # basic makefile
README                  # user manual
README_DE               # German user manual
README_LANGLIST         # list of supported languages
README_PLUGINS          # plug-in manual
README_REGEX            # regular expression manual
README_RELEASE          # information for packagers
TODO                    # just ideas, no plans


2. Dependencies
===============

In order to compile highlight, you need to install Lua (5.1, 5.2 or LuaJIT as
devel package) and Boost (at least the header files).
The optional GUI requires Qt (4 or 5) and its development tools (qmake).


3. Basic installation
=====================

 1. tar xzvf highlight-x.x.tar.gz

 2. cd highlight-x.x

 3. make help

 4. make / make cli   (compile static library and the CLI interface)
    make lib-static   (optional, compile static library only)
    make lib-shared   (optional, compile shared library only)
    make gui          (optional, compile static library and the Qt 4.x GUI)

 5, make install
    (depending on your installation destination, you need to be root)

 6. make install-gui (optional)
    Install additional files if you have compiled the highlight GUI binary.
    (depending on your installation destination, you need to be root)

 7. make clean (optional)

 8. make apidocs (optional)
    (you need to have doxygen installed)

 After the compilation of the CLI or GUI, a library (libhighlight.a) was
 generated which may be used for other C++ projects.

 Highlight's default data directory is /usr/share/highlight.
 You may alter this directory at compile time or at run time:
 - See the makefile how to add a compiler directive which defines an
   installation directory (data_dir variable)
 - Use the --data-dir option to define a new directory at run time. You may
   want to save this parameter in the highlight configuration file
   ($HOME/.highlightrc)
 - See the makefile to change the configuration file directory
   (conf_dir variable).


4. Known compiler issues
========================

Highlight was tested with gcc 4.x. It will not compile with gcc 2.x.


5. LaTeX unicode support
========================

To enable UTF-8 support in LaTeX, the ucs package has to be installed.
See the following package names or sources:

Fedora: tetex-unicode
SuSE:   latex-ucs

Source: http://www.unruh.de/DniQ/latex/unicode/


6. Lazy pointer issue under MacOS X
===================================

Stripping the highlight binary causes program termination at runtime:

dyld: lazy symbol binding failed: lazy pointer not found
dyld: lazy pointer not found
Trace/BPT trap

To avoid this issue, edit the makefile to not strip the binary after
linkage (see src/makefile, LDFLAGS variable).


7. Static linking (to run highlight as service)
===============================================

If highlight cannot be run as service because of shared linkage, link
it with the -static option (see src/makefile, LDFLAGS variable).


8. Known distribution issues
============================

Linux Mint

There is a system script called highlight which is located in a preferenced path: 

mintsystem provides: /usr/local/bin/highlight
 highlight provides: /usr/bin/highlight

Calling this script with the true highlight command line options will have no effect. 
See bug tracker items: https://bugs.launchpad.net/linuxmint/+bug/593583 and
                       https://bugs.launchpad.net/linuxmint/+bug/815005
