PDFedit readme
==============

PDFedit is distributed under terms of GNU GPL in version 2.
See doc/LICENSE.GPL for full license text.
See doc/AUTHORS for full list of authors and contributors.
For other more detailed documentation, look into "doc" subdirectory.
File doc/user/user_doc.html contain more detailed installation instructions
(in the Installation section) and list of required libraries.

Contact
=======
Feel free to contact us with any question via our public
pdfedit-support@lists.sourceforge.net mailing list. Note that you have to 
be subscribed if you want to post messages to the list (subscription form
is at https://lists.sourceforge.net/lists/listinfo/pdfedit-support).
Mailing list archive is public visible also without registration. Please 
try to look into the archive before you post your question and append 
an existing thread rather than create a new one.

If you want to be informed about important news you can register to the 
pdfedit-news@lists.sourceforge.net mailing list. You can subscribe at
https://lists.sourceforge.net/lists/listinfo/pdfedit-news

All public mailing lists are listed at
http://sourceforge.net/mail/?group_id=177354


Prerequisites
=============
Base (kernel)
-------------
Boost libraries must be installed. See detailed description about configure
parameters if you have some unusual installation.
Freetype library is almost necessary, because nearly all PDFs use these fonts.
T1 font library is also recommended.

Tests
-----
Our tests are based on CPPUNIT library, so it has to be present on your 
system. See detailed description about configure parameters if you have 
some unusual installation.

Gui
---
Make sure you have all needed libraries (qt3, boost and xlib) along with their 
headers. 
You also need the environment variable QTDIR to be set to directory in which 
the Qt toolkit (version 3) is installed. Many distributions already set this 
when installing Qt, but some of them don't. In that case, you have to set the 
QTDIR manually. Usually it is set to something like /usr/qt/3 or /usr/share/qt3
(use e. g. export QTDIR=/usr/share/qt3 to set the variable if this is your 
case).  
Also, while usually not needed, QMAKESPEC may be set to match your system type.
For most systems it is unnecessary to set it, although it may be needed if you
cross-compile (like producing i386 binaries on amd64 platform) or in some rare
configurations. Once you set QTDIR, you may try typing "ls $QTDIR/mkspecs".
QMAKESPEC should be set to name of one of the directories that are in mkspecs
subdirectory in the Qt directory.
See http://www.digitalfanatics.org/projects/qt_tutorial/chapter04.html or 
http://doc.trolltech.com/3.0/qmake-guide.html for more information.
QTDIR is used also for qmake (tool for generating makefiles from QT project
files) detection. By default, this is stored somewhere under QTDIR directory
(typically QTDIR/bin/), but there are also platforms, where this is not 
exactly true. If you have such a platform, try to use --with-qmake-dir
parameter to configure (see bellow)

Documentation
=============
There are 3 levels of documentation in this project.
* Basic - in the form of the man page which is always installed 
* doxygen - programming documentation extracted from sources and
	    processed by doxygen tool. Obviously, doxygen has to
	    be installed.
	    This documentation is not created and installed by
	    default and you have to explicitly enable it by
	    --enable-doxygen-doc parameter to ./configure
	    Result documentation is placed in the DOC_PATH/doxygen
	    directory (DOC_PATH is PREFIX/share/doc/pdfedit)
* advanced - design documentation which describes inner data 
	    structures, algorithms and relations from the 
	    programmer perspective. This one is useful if you
	    want to develop PDFedit or 3rd party application based
	    on PDFedit.
	    This documentation is not created by default too and
	    you have to enable it by configure parameter 
	    --enable-advanced-doc. We are using xml based docbook
	    format, so you have to have docbook xsl and xsltproc
	    installed. 
	    Result documentation is placed in the DOC_PATH/design/
	    directory.

Configuration
=============
 Run:
  ./configure [parameters]

NOTE for those who use sources from CVS. configure is NO MORE part of the
CVS tree!!! You have to generate it. This can be done simply by
$ autoconf
in the root of the checkout project. Note that you have to have autoconf
package installed on your machine.

Simple run without any parameter results in default configuration where 
application is compiled in release mode (optimizations turned on, debug
symbols are not present, compilation warnings are eliminated), GUI is
enabled, doxygen documentation is generated, no kernel tests (stored in 
src/kernel/tests/) are compiled and application will be installed into the
/usr/local/pdfedit directory.


Configure features
------------------
You can change this behavior with following parameters (feature is used
if --enable- prefix is used, contrary --disable- prefix turns off this
feature - e.g. if feature name stack-protector => --enable-stack-protector 
uses this feature):
	-stack-protector - adds stack protector parameter to the compilation
	 flags. Disabled by default, because not all compilers support this
	 feature (gcc > 4.1 supports it)

	-release - controls compilation flags for release mode (no debugging
	 needed). This is used by default. It means that optimizations are
	 turned on, debug information is not included in the result binary.
	 If you want to debug or do some development, --disable-release is
	 strongly recommended.

	-debug-info - if --enable-release is used and you still need debug
	 information (e.g. when application crashes to have some reasonable
	 stack traces) use --enable-debug-info. This parameter feature would
	 be ignored if --disable-release is used.
	
	-observer-debug - just for developers only. Disabled by default. If
	 turned on, some more debug information is added to the kernel code
	 to enable debugging observers based code.

	-gui - Creates GUI for PDFedit (pdfedit binary). Enabled by default. 
	 If --disable-gui is used, no GUI (no pdfedit binary is created).
	
	-kernel-tests - Compiles all kernel tests (in src/kernel/tests). 
	 Disabled by default and intended for developers/testers only. Note
	 that this requires to have CPPUNIT installed on your system.
	
	-doxygen-doc - generates also doxygen documentation useful for 
	 programmers. Disabled by default. Note that doxygen has to be
	 installed for this feature.

	-advanced-doc - generates also docbook design documentation.
	 Disabled by default. Note that docbook and its prerequisites
	 has to be installed for this feature.


Libraries and binaries specification
------------------------------------
You can also control search paths for required libraries and binaries:

	- Freetype2 font library
	./configure --with-ft-prefix=PATH_TO_YOUR_FREETYPE2
	resp. (for T1)
	
	- T1 font library
	./configure --with-t1-includes=PATH_TO_YOUR_T1_HEADERS \
		--with-t1-library=PATH_TO_YOUR_T1_LIB
	
	- CPPUnit
	./configure  --with-cppunit-prefix=PATH_TO_YOUR_CPPUNIT

	- Boost
	./configure --with-boost=YOUR_BOOST_INSTALLATION

	- qmake is searched in $QTDIR/bin, /usr/lib/qt3/bin and
	  current PATH directories. If you have qmake installed
	  in other directory, use:
	./configure --with-qmake=QMAKE_BINARY_WITH_PATH

	- doxygen is searched in /usr/bin , /usr/local/bin and 
	  current PATH directories. If you have doxygen installed
	  in other directory, use:
	./configure --with-doxygen=DOXYGEN_BINARY_WITH_PATH

	- xsltproc is  searched in /usr/bin , /usr/local/bin and 
	  current PATH directories. If you have xsltproc installed
	  in other directory, use:
	./configure --with-xsltproc=XSLTPROC_BINARY_WITH_PATH

	- docbook xslt files are necessary for xsltproc to generate
	  correct output from docbook xml files. There are many
	  places where these files can be found. As many systems
	  use different directories and there is no general way
	  to detect, we are using file doc/tools/docbook_xslt_paths
	  to define all possible directories which are searched.
	  If you are sure that you have installed package with
	  this file (usually stored ...html/dobook.xsl) add its 
	  absolute path  to this file (each directory should be on the 
	  separate line and can use wildchars). If you report missing 
	  directory for your platform, we can add it in the next release.


Installation directories
------------------------
All files are by default installed under /usr/local subdirectory (binary
into /usr/local/bin, config files into /usr/local/share/pdfedit etc.).
This location can be changed by --prefix parameter to configure (PREFIX
in the following).

PDFedit binary location can be controlled by --exec-prefix (EPREFIX in
the following) and it is stored under EPREFIX/bin. EPREFIX is the
same like PREFIX by default.

Documentation files are copied to PREFIX/share/pdfedit/doc, configuration
files and scripts are copied to PREFIX/share/pdfedit and man page is
copied to PREFIX/share/man/man1.

If you need to change installation root (e. g. if you are packager and
want to create package) use
	--with-root-dir=YOUR_INSTALLATION_ROOT_DIR
configure parameter and all data will be moved to the selected directory
after you do make install (using correct PREFIX and EPREFIX of course)

Installation directories for specific parts (binary, documentation, 
configuration files) can be also controlled by configure parameters.
	--bindir controls directory where the pdfedit binary is copied
	--docdir controls directory where documentation is copied
	--mandir controls directory where the man page is copied. Note that
	  we provide only man 1 pdfedit, so that man page is actually copied
	  under man1 sub-directory under specified one.
	--datadir controls directory where configuration files are stored
	  (files are actually stored in pdfedit package name subdirectory)

You can use following variables if you want to customize above directories:
	prefix - value set as --prefix (usually /usr/local)
	exec_prefix - value set as --exec_prefix (usually same as PREFIX)
	datarootdir - root directory for all pdfedit data (usually PREFIX/share)
	version - current version
	package_name - installed package name

Example for multiple simultaneous versions installation:
	# Note that quotes are necessary here because bash (and some other 
	# shells may too) would run subshell for $(expression)  otherwise
	# Also note that man page will be overwritten by each installation.
	./configure --bindir='$(exec_prefix)/$(package_name)-$(version)' \
		--docdir='$(datarootdir)/doc/$(package_name)-$(version)' \
		--datadir='$(datarootdir)/$(package_name)-$(version)' 


Compilation
===========

After configure successfully finishes, run "make" in this directory to start
compilation (note that GNU make is preferred bacause we are using some GNU
make features which might be not available with other make implementations).

If you need (for what ever reason) to change or explicitly specify other than
default compiler, you can do it during configuration phase by passing your
compiler as CC and CXX configure parameters. The first one stands for c files 
compiler while the second is used for c++ files.
Lets say that we have gcc v 4.2 as default and want to compile with the newest
gcc 4.3. Then you should do something like (name of compiler binary may
vary on different systems - this one is for Debian):
	./configure CC=gcc-4.3 CXX=g++-4.3

Note that CFLAGS and CXXFLAGS which can be standardly passed to configure
are ignored by our configure script.

Installation
============
 To install editor, run
  make install

Note that all files will be installed according to defined prefix and 
if --with-root-dir was specified for configure, then prefix is relative 
to the specified root.

Cygwin build
============
PATH in cygwin must contain these three directories
/bin			(most required executables are stashed here)
/usr/X11R6/bin		(some libraries are here)
/usr/lib/qt3/bin	(qmake must be in PATH)

You can use cygwin_build.bat to start the build process (you will need 
to set CYGWIN_ROOT in the file first). This will create the package in 
/tmp/pdfedit-package and create pack.bat to pack the package with 7-zip


FreeBSD build
=============
Here is the short howto for PDFedit compilation and installation on FreeBSD 6.2 
(Qt 3.38, Xorg 7.2). Thanks to Hao Chen.

# untar current sources (this was done for 0.3.1 version)
tar zxvf pdfedit-0.3.1.tar.bz2
cd pdfedit-0.3.1
setenv QTDIR /usr/local
setenv QMAKESPEC /usr/local/share/qt/mkspecs/freebsd-g++
setenv LOCALBASE /usr/local
./configure  --with-t1-library="${LOCALBASE}/lib" \
	--with-t1-includes="${LOCALBASE}/include"

#make sure you see this:
#checking for T1_InitLib in -lt1... yes
#using t1 library

Our makefiles use some extensions of GNU make, so it is recomended to use
gmake instead!

NetBSD installation
===================
Package for NetBSD is available on http://pkgsrc.se/wip/pdfedit


Debian package
==============
The package for the Debian is in testing branch at the moment. 
See http://packages.debian.org/unstable/utils/pdfedit

The package for the Ubuntu can by found at 
http://packages.ubuntu.com/gutsy/utils/pdfedit


RPM based distros
=================
NEEDS update

Gentoo package
==============
Package is available on sunrise overlay repository
which should be available in following way:

emerge -va layman
echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf
layman -f -a sunrise

pdfedit is then installed by:
ACCEPT_KEYWORDS=~x86 emerge -av pdfedit