============
TET Cookbook
============

The TET Cookbook is a collection of TET code samples for solving specific
PDF content extraction problems. It is maintained as a list of Java programs
and XSLT scripts.

TET Cookbook topics can be used as follows:

- The code samples can be used with the TET API. The Cookbook topics are
  written in Java, but can easily be ported to other programming languages
  since the TET API is identical for all supported language bindings.
  
- XSLT samples demonstrate postprocessing of TETML, the XML output created by
  TET for the contents of PDF documents. TETML can be created with the TET API
  (any language binding) and the TET command-line tool.
  
- Cookbook topics in the category "tet_and_pdflib" demonstrate the combination
  of both products; they require PDFlib+PDI in addition to TET.
  
- Examples for the pCOS interface (which is integrated in TET) are presented
  in the pCOS Cookbook which is maintained separately.

All Cookbook topics can be used with the free TET evaluation packages.


Prerequisites
=============

- The TET binary library for Java and the TET command line tool must have
  been installed. Some examples require the PDFlib+PDI library.

- The Cookbook topics can conveniently be compiled and run with the Java
  build tool Apache Ant (see ant.apache.org).
  Alternatively, you can manually compile and run the samples.
  
- The TET Cookbook package contains an Eclipse project file that allows
  the direct import of the Cookbook into an Eclipse workspace
  (see "Importing the TET Cookbook into Eclipse" below).
  
- The Java Development Kit (JDK) is required.


Installing the Cookbook
=======================

- Download the TET-Cookbook archive from www.pdflib.com and unpack it.
  This will create the following TET Cookbook structure:
  
  TET-Cookbook
      /bin
      /doc
      /input
      /java
          /build
          /src/com/pdflib/cookbook/tet/ ... /*.java
          build.xml
      /xslt
      .classpath
      .project    
	    
- Copy "TET.jar" and the platform-dependent TET JNI library
  ("tet_java.dll" for Windows, "libtet_java.so" for Linux etc.) from the
  "bind/java" directory of the PDFlib TET distribution to the
  "TET-Cookbook/java" subdirectory.  In the same manner add the PDFlib
  JAR file and library to the "java" subdirectory of the "TET-Cookbook"
  project if necessary.
  
- Copy "tet.exe" (on Windows) or "tet" (on other platforms) from the "bin"
  directory of the PDFlib TET distribution to the "TET-Cookbook/bin"
  subdirectory.
      
- Copy the "resource" directory of the PDFlib TET distribution to
  "TET-Cookbook/resource" if you need to extract CJK text which requires CMaps.


Compiling and Executing Cookbook topics with Ant
================================================

- For running the XSLT example programs, go to the "xslt" directory of the
  Cookbook and execute the following commands:
  
  ant               To execute all topics. 
                    Any output files will be created in the current directory.

  ant <topic name>  To execute a particular topic.
  
  ant clean         To delete all output files.
  
- For running the Java samples go to the the "java" directory of the
  Cookbook and execute the following commands:
  
  ant               To compile and execute all topics. 
                    The class files are stored in the build subdirectory.
                    Any PDF output documents will be created in the current
                    directory.

  ant <topic name>  To compile and execute a particular topic.

  ant build         To compile all topics.
  
  ant clean         To delete all class and PDF files.
  
- Depending on the nature of the text, the platform and the environment it is
  possible that not all characters are displayed correctly in the text console.
  The reason is most likely that Java has set a different output encoding than
  the text console.
  
  You can find out what default encoding is set for Java by running the
  following Java program:
  
    public class print_default_encoding {
        public static void main(String[] args) {
            System.out.println(System.getProperty("file.encoding"));
        }
    }
  
  You can override the default encoding by setting the Java system property
  "file.encoding" to the desired encoding via the environment variable
  ANT_OPTS.
  
  On Windows in a command window:
  
    set ANT_OPTS=-Dfile.encoding=<desired encoding>
  
  On Unix or Linux in a shell:
  
    export ANT_OPTS=-Dfile.encoding=<desired encoding>
    
  Typical situations might be:
  
    - You are running the Ant build in a Windows command window. Java has
      "Cp1252" set as the default encoding, the command window has set
      codepage 850. 
      
      To make the Ant build use codepage 850 for the output, execute the 
      following statement in the command window before running the Ant build:
      
        set ANT_OPTS=-Dfile.encoding=Cp850
      
      To see what codepage is set in a command window, type the following command:
      
        chcp
    
    - You are running the Ant build on macOS. Java has "MacRoman" set
      as the default encoding, and the shell has set UTF-8 as the encoding,
      for example "LANG=de_DE.UTF-8".
      
      To make the Ant build use UTF-8 as the output encoding, set ANT_OPTS
      like this before executing the Ant build:
      
        export ANT_OPTS="-Dfile.encoding=UTF-8"
      
      To see the current setting of the LANG environment variable that defines
      the encoding for the Shell, type the following command:
      
        echo $LANG

- For running the XSLT programs, go to the "xslt" directory of the Cookbook,
  and execute the following commands:
  
  ant               to execute all topics.

  ant <topic name>  to execute a particular topic.
  
  ant clean         to delete all output files.


Manually compiling and executing Cookbook Java topics
=====================================================

As an alternative to using ant you can compile and run the topics manually
as follows:

- cd to TET-Cookbook/java

- Create the output directory for storing the class files:
  
    mkdir build 

- Compile a class file as follows: 
  
  On Windows, Linux or Mac (enter command in one line): 
  
  javac -d build -classpath TET.jar -sourcepath src
        src/com/pdflib/cookbook/tet/font/font_statistics.java

- Execute a class file as follows: 
  
  On Unix, Linux or Mac (enter command in one line): 
  
  java -Djava.library.path=. -classpath build:TET.jar
        com.pdflib.cookbook.tet.font.font_statistics ../input/FontReporter.pdf
  
  On Windows (enter command in one line):
  
  java -Djava.library.path=. -classpath build;TET.jar
        com.pdflib.cookbook.tet.font.font_statistics ..\input\FontReporter.pdf

- The same comments as for the Ant build regarding the output encoding apply.
  To force Java to use a desired output encoding pass the system property
  "file.encoding" directly on the command line, e.g. for Windows:
  
  java -Dfile.encoding=Cp850 -Djava.library.path=. -classpath build;TET.jar
        com.pdflib.cookbook.tet.font.font_statistics ..\input\FontReporter.pdf


Manually executing XSLT stylesheets
===================================

Depending on the platform there are different tools available for running
XSLT stylesheets from the command line.

On Unix/Linux there may be the "xsltproc" command installed. Use it for example
like this to execute a stylesheet while specifying a stylesheet parameter:

  xsltproc --output FontReporter.html --param toc-generate 0 tetml2html.xsl \
    FontReporter.tetml

Microsoft provides the "msxsl.exe" tool as a free download:

http://www.microsoft.com/downloads/details.aspx?familyid=2FB55371-C94E-4373-B0E9-DB4816552E41

Use it for example like this to execute a stylesheet while also specifying a
stylesheet parameter:
  
  msxsl.exe FontReporter.tetml tetml2html.xsl -o FontReporter.html toc-generate=0


Importing the Cookbook project into Eclipse
===========================================

- Choose "File, Import, General, Existing Projects into Workspace" and
  press "Next".

- Click on "Select archive file:" and browse to the TET Cookbook archive file
  ("TET-Cookbook.tar.gz" or "TET-Cookbook.zip").

  The project "TET-Cookbook" will be displayed in the "Projects:" section.

- Click "Finish" to import the project into your workspace.
  
- Copy "TET.jar" and the platform-dependent TET library ("tet_java.dll"
  for Windows, "libtet_java.so" for Linux etc.) from the "bind/java"
  directory of the PDFlib TET distribution to the "java" subdirectory of the
  "TET-Cookbook" project. In the same manner add the PDFlib and/or PLOP
  JAR files and libraries to the "java" subdirectory of the "TET-Cookbook"
  project if necessary.
  
- Copy "tet.exe" (on Windows) or "tet" (on other platforms) from the "bin"
  directory of the PDFlib TET distribution to the "TET-Cookbook/bin"
  subdirectory.
  
- Copy the "resource" directory of the PDFlib TET distribution to
  "TET-Cookbook/resource".
  
- Refresh the "TET-Cookbook" project
  
- To use the included build.xml Ant build file:

  - Open the "Ant" view in the "Java" perspective.
  
  - Right-click the "Ant" view and select "Add Buildfiles".
  
  - Browse to the "build.xml" file in the "java" subdirectory of the
    "TET-Cookbook" project. 
    
  - Run individual topics by clicking on the corresponding entry in the 
    "Ant" view, or run all with the "run-all-topics" target.