Starting with version 0.4.4 YajHFC provides a (limited) interface to provide custom file filters.
A YajHFC file filter is specified as follows:
- It is a program that converts its input file to PDF or PostScript
- The input file is given on the command line
- The output has to be written to stdout and must be in PDF or PostScript format
- When the conversion fails, the program should exit with a non-zero exit code
To specify a file filter, go to Options→Advanced Settings→File converters:
There, you can see the file formats recognized by YajHFC and the filter filter provided for it (or (none) if there is no file filter).
The "file format" Any is used for any file not falling into the other categories.
Currently you cannot add new file formats to this list, but only edit the file filters for the formats listed here (PDF and PostScript cannot be edited, because there is no conversion performed for these formats).
To add a file filter for a new format (or override an internal file filter provided by YajHFC), just enter the command line for the conversion program into the table.
In the command line specification, you can use the following placeholders:
|%s||the file to convert|
|%p||the name of the paper size (e.g. A4, LETTER, ...)|
|%h||the height of the paper in tenths of mm (e.g. 297 for A4)|
|%w||the width of the paper in tenths of mm (e.g. 210 for A4)|
|%F||the desired output format (only as a hint; either PDF or PostScript)|
Please note that %F is only a hint: It is perfectly legal to always output PDF or always output PostScript regardless of the value of this parameter (it is only there to be able to avoid an additional conversion from PostScript to PDF or from PDF to PostScript if the converter can easily produce both formats).
YajHFC checks if the filer script/program exits with a non-zero exit code. If it does, the user gets an error message (currently Non-zero exit code of command (exit code): last 10 lines of output to stderr)
If you want to display a custom error message to the user, you can use the "magic" exit code of 111. If the filter exits with code 111, YajHFC only displays the last 10 lines of output to stderr, without the "Non zero exit code..." header.
If the filter exits with a zero exit code, YajHFC checks if the output is PDF or PostScript. If it is not, the user also gets an error message.
To use the a2ps tool on Linux to pretty-print plain text files, enter the following command line for PlainText:
a2ps -1 -o - -M %p "%s"
To add support for file formats not listed in the list, you will have to use the Any format and then do a file format detection in the filter invoked by YajHFC.
A simple Linux shell script for the Any file format could look like this, for example:
#!/bin/sh # Example YajHFC file filter for the "Any" file format # Invocation: filefilter.sh %p %w %h %F "%s" if [ $# -ne 5 ]; then echo 'Usage: filefilter.sh %p %w %h %F "%s"'>&2 exit 1; fi # Exit when a command fails set -e PAPERSIZE="$1" PAPERWIDTH="$2" PAPERHEIGHT="$3" TARGETFORMAT="$4" INPUTFILE="$5" case "$INPUTFILE" in *.zip) # List the contents of zip files (as an example) unzip -lv "$INPUTFILE" | a2ps -1 -M $PAPERSIZE -o - - ;; #*.doc|*.odt) # # Do something else... # ;; *) echo 'Error: Unknown file format for file' $(basename "$INPUTFILE") >&2 exit 111 ;; esac
This script then can be saved as (for example) filefilter.sh, made executable (chmod 0755 filefilter.sh) and invoked as filefilter.sh %p %w %h %F "%s" (like in the image above).
This is only a minimal example to illustrate how a filter script works, however: It "recognizes" file formats only by the file name extension and the only "format support" it adds is listing and pretty-printing the contents of ZIP files.
Possible extensions could be:
- Detect the file format by using the file utility
- Use a tool like unoconv to add support for OpenOffice documents, Word documents, ...
- Create a similar script for Windows
If you have created your own filter script and would like to share it, please feel free to write to firstname.lastname@example.org to have it added to this page.