Texcaller
Modules | Functions
Texcaller C interface

The Texcaller library is a convenient C interface to the TeX command line tools. More...

Modules

 Internals of the Texcaller C interface

Functions

void texcaller_convert (char **result, size_t *result_size, char **info, const char *source, size_t source_size, const char *source_format, const char *result_format, int max_runs)
 Convert a TeX or LaTeX source to DVI or PDF.
char * texcaller_escape_latex (const char *s)
 Escape a string for direct use in LaTeX.

Detailed Description

The Texcaller library is a convenient C interface to the TeX command line tools.

The following example program demonstrates how this library is meant to be used:

#include <texcaller.h>
#include <stdio.h>
#include <string.h>

int main()
{
    char *latex =
        "\\documentclass{article}"
        "\\begin{document}"
        "Hello world!"
        "\\end{document}";

    char *pdf;
    size_t pdf_size;
    char *info;

    texcaller_convert(&pdf, &pdf_size, &info,
                      latex, strlen(latex), "LaTeX", "PDF", 5);

    if (pdf == NULL) {
        printf("Error: %s\n", info == NULL ? "Out of memory." : info);
    } else {
        printf("Generated PDF of %i bytes. Details:\n\n%s", (int)pdf_size, info);
    }

    free(pdf);
    free(info);
    return 0;
}

Since Texcaller supports pkg-config, compiling and linking in a portable way is as simple as:

cc -o example example.c `pkg-config texcaller --cflags --libs`

Assuming that everything is installed in default locations on your system, the following simpler command will also work. However, don't hard code that into your build system!

cc -o example example.c -ltexcaller

Function Documentation

void texcaller_convert ( char **  result,
size_t *  result_size,
char **  info,
const char *  source,
size_t  source_size,
const char *  source_format,
const char *  result_format,
int  max_runs 
)

Convert a TeX or LaTeX source to DVI or PDF.

This function is reentrant. Temporary files are always cleaned up. The TeX interpreter is automatically re-run as often as necessary until the output becomes stable. The interpreter is always run in batch mode and is disconnected from stdin, stdout and stderr. That way, it won't ever get in your way even if there are issues with your input source. Instead, all important information is simply collected in the info string.

Parameters:
resultwill be set to a newly allocated buffer that contains the generated document, or NULL if an error occured.
result_sizewill be set to the size of result, or 0 if result is NULL.
infowill be set to a newly allocated string that contains additional information such as an error message or TeX warnings. When out of memory, info will be set to NULL (and result will be set to NULL, too).
sourcethe source to convert
source_sizesize of source
source_formatmust be one of:
  • "TeX"
  • "LaTeX"
result_formatmust be one of:
  • "DVI"
  • "PDF"
max_runsmaximum number of TeX runs, must be ≥ 2. If the output doesn't stabilize after max_runs runs, the function will fail and result will be set to NULL.
char * texcaller_escape_latex ( const char *  s)

Escape a string for direct use in LaTeX.

That is, all LaTeX special characters are replaced with proper LaTeX elements. Note that all other unicode characters remain as they are, so be sure to use the inputenc package in your LaTeX document:

\usepackage[utf8x]{inputenc}

For example, the following string:

Téxt → "with" $peciäl <characters>

is escaped to:

Téxt → {''}with{''} \$peciäl \textless{}characters\textgreater{}

This function is reentrant.

Parameters:
sthe string to escape
Returns:
a newly allocated string containing the escaped value, or NULL when out of memory.