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

This file describes do's and don'ts, good practices, and requirements when
packaging TeXworks.

When you have read this far, you are probably interested in packaging TeXworks.
First of all, thank you for your commitment, it is very welcome. Before you
start, however, you should check that no packages for the system you intend to
target exist already. Currently, packages for Windows, Mac OS X, and Ubuntu are
provided by the project maintainers, and packages for several other Linux
distributions have been contributed by members of the community.

If you package TeXworks successfully, please drop by the mailing list and tell
us about it :).


General guidelines
==================

This section describes how TeXworks should be packaged. It does not deal with
the building process itself, however. Building in general is documented in the
README and on http://code.google.com/p/texworks/w/list, while special
considerations concerning packaging are discussed in the following sections.
This section deals with the principal decisions.

 * TeXworks consists of the core program and plugins. If possibly, the plugins
   should be made available separately (unless noted otherwise). The are to be
   considered optional (Debian policy: they are suggested, not recommended,
   meaning that running TeXworks without them is perfectly reasonable).

 * All plugins that can be built should be built.

 * Stable releases feature a copy of the manual. Like the plugins, this should
   be packaged, preferably as a separate, optional package (Debian policy: a
   suggested package).

 * It is strongly recommended to distribute TeXworks with the poppler encoding
   data as well as the 14 PDF base fonts or suitable (i.e., metrically
   equivalent) replacements. On Linux, these are typically provided by the
   system and/or packages which the TeXworks package should depend on. Note that
   this is not a strict dependence, as TeXworks will run without poppler-data or
   the base-14 fonts, but some files may not be displayed correctly (Debian
   policy: the packages are recommended, meaning that they are found on all but
   the most unusual systems). Note that when providing poppler-data and/or fonts
   yourself in the package, you most likely will need to patch the poppler
   library itself as well.
   See below for further information on this issue and how to test proper
   functionality.


Building specialties
====================
When building TeXworks for packaging, you will probably face special
requirements, like installing in special locations to suit your packaging
process. This section discusses where and how such modifications to the default
behavior can be implemented.

The TeXworks build process supports several variables that can be set when
invoking qmake. To set a variable VAR1=abc and VAR2=xyz, invoke qmake as
    qmake-qt4 'VAR1=abc' 'VAR2=xyz' TeXworks.pro

The most important variable you must always set is TW_BUILD_ID. This ID should
uniquely identify the build process (who built it, for what platform, etc.) so
that packaging-related problems that are reported to the general mailing list
can be passed on to you, the packager.

In addition, several directory variables can be set on *nix (on Windows and the
Mac, packages are self-contained and don't usually install into (separate)
system directories):
    INSTALL_PREFIX   base prefix [/usr/local]
    BIN_DIR          path to install the main program [INSTALL_PREFIX/bin]
    TW_PLUGINPATH    path to install plugins [INSTALL_PREFIX/lib/texworks]
    DATA_DIR         base prefix for data files [INSTALL_PREFIX/share]
    TW_HELPPATH      path to install help files [DATA_DIR/texworks-help]
    TW_DICPATH       path to look for spell checking files (dictionaries)
                     [/usr/share/myspell/dicts]
    DOCS_DIR         path to install general docs (README, NEWS, COPYING)
                     [DATA_DIR/doc/texworks]
    ICON_DIR         path to install icons [DATA_DIR/pixmaps]
    MAN_DIR          path to install man files [DATA_DIR/man/man1]
    DESKTOP_DIR      path to install .desktop files [DATA_DIR/applications]
Note that generated Makefiles still honor the INSTALL_ROOT= directive to take
INSTALL_PREFIX as a relative path under INSTALL_ROOT as opposed to an absolute
path.

Apart from these variables, qmake is controlled primarily by TeXworks.pro and
similar .pro files in subdirectories. These contain all definitions and settings
that you may need to change under special circumstances. E.g., they contain
directives for finding and linking libraries that may need adjustment to suit
your needs.

Apart from that, the only line you should need to pay attention to is
    QMAKE_CXXFLAGS += -DHAVE_POPPLER_XPDF_HEADERS
which needs to be commented if you don't have the xpdf headers provided by
poppler. This entails that no custom poppler data will be supported (used on
Windows and the Mac; requires a customized build of the poppler library - see
below) and therefore is not recommended.


Poppler
=======

As mentioned in the guidelines, there are several intricacies concerning the
poppler library.

In order to properly display PDF files without embedded fonts - and to conform
to the PDF standard - TeXworks package must ensure that the base 14 fonts are
available on the system. The preferable way to do that is to pull in system
packages and/or use alternative fonts found on the system. The remaining files
can be obtained, e.g., from http://www.ctan.org/tex-archive/fonts/urw/base35
(note that those fonts have been renamed according to
http://www.tug.org/fontname/html/URW-fonts.html which must be undone as poppler
expects the original filenames). The following pfb files are needed:
d050000l.pfb, n019003l.pfb, n019004l.pfb, n019023l.pfb, n019024l.pfb,
n021003l.pfb, n021004l.pfb, n021023l.pfb, n021024l.pfb, n022003l.pfb,
n022004l.pfb, n022023l.pfb, n022024l.pfb, s050000l.pfb.

If you provide the base 14 fonts yourself, you need to make sure poppler picks
them up. To achieve that, you most likely will need to patch poppler
accordingly. See lib-patches/poppler-win32-font-handling.patch for an example
for poppler-0.16 on Windows.

To check if the fonts are picked up correctly, use the base14-fonts testcase
from http://texworks.googlecode.com/svn/trunk/testcases/.

Moreover, the poppler library needs the poppler-data from
http://poppler.freedesktop.org/ (this particularly affects displaying CJK
documents). By default, TeXworks looks for a folder named "poppler-data"
alongside the main application on Windows and Mac (see src/TWApp.cpp -
TWApp::init()). It only sets this directory once while starting up, however, so
you need ensure poppler doesn't mess with it by building poppler with the
lib-patches/poppler-qt4-globalparams.patch patch.

To check if poppler-data is picked up properly, use the poppler-data testcase
from http://texworks.googlecode.com/svn/trunk/testcases/.


Other libraries and patches
===========================

 * Qt 4.7.0 and 4.7.1 have a bug crashing TeXworks occasionally when using the
   "Highlight current line" feature together with "Wrap Lines" due to a memory
   overflow. Use lib-patches/qt-4_7-qpathclipper.patch to fix that.


Further information and help
============================

Homepage:     http://www.tug.org/texworks/
Development:  http://code.google.com/p/texworks/
Bugs:         http://code.google.com/p/texworks/issues/list
Mailing list: http://tug.org/mailman/listinfo/texworks
