Texcaller C interface

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

Collaboration diagram for Texcaller C interface:

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. More...
char *	texcaller_escape_latex (const char *s)
	Escape a string for direct use in LaTeX. More...

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

texcaller_convert()

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

result	will be set to a newly allocated buffer that contains the generated document, or NULL if an error occured.
result_size	will be set to the size of result, or 0 if result is NULL.
info	will 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).
source	the source to convert
source_size	size of source
source_format	must be one of: "TeX" "LaTeX" "XeTeX" "XeLaTeX" "LuaTeX" "LuaLaTeX"
result_format	must be one of: "DVI" (only for source formats "TeX" and "LaTeX") "PDF"
max_runs	maximum 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.

texcaller_escape_latex()

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

s	the string to escape

Returns

a newly allocated string containing the escaped value, or NULL when out of memory.