A GUI frontend to Apache FOP.

FOPLaboratory

Download

Program-archives
foplaboratory_0.8.2.zip
foplaboratory_0.8.2.7z
SHA256 checksums
foplaboratory_0.8.2.zip: 2b93662f682b87edd567c2322fc50ffe7be86bac8989091a79ed1780223bc807
foplaboratory_0.8.2.7z: 076b4606286e108fbc5bf07592390e7952fd33459635cbe6626197146acb9ed4
My digital signatures for the archives
made with DSA key ID 74A227D5
foplaboratory_0.8.2.zip.sig
foplaboratory_0.8.2.7z.sig

FOPLaboratory is free software under the GNU General Public License.

Copyright (C) 2011
Michael Uplawski <michael.uplawski@uplawski.eu>
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Contents of the Archive

The Zip-file contains the following files and sub-folders:

doc A directory, containing documentation (e.g. this text)
several files *.qm Locale-specific translations, as they are read by FOPLaboratory to show labels and other text in other languages than English. There are files for French and German locales, but the French translation is not done, yet.
several files *.ts Translation-files in XML-format, allowing a translator to add her/his own translation of the original English text-fragments, displayed on the FOPLaboratory user-interface. The Qt-tool Qt-Linguist can create *.qm files from these translation-files.
Changes.txt A list of changes in program-versions.
FOPLaboratory.pro The project file defines the components of the program, translations inclusive. It is read by the QMake utility and needed to create the Makefile.
license.txt The Gnu General Public license.
examples Contains an examplary XML-file, XSL style-sheets and configuration-files to fop and tidy. One of the style-sheets is faulty to demonstrate how FOPLaboratory reacts in such a case.
images Currently contains only a program-icon.
src The FOPLaboratory source-code. Once a Makefile has been created, the files in this directory will be compiled into the executable FOPLaboratory-binary.

Installation

I do not hand out ready-to-use binary executables of the FOPLaboratory utility, but only the C++/Qt source-code of the program.

In consequence, you will have to compile the software yourself. The reasons for this:

Preparation

The QMake utility is needed. It is part of the Qt Development Framework, which you must install to compile FOPLaboratory. For the later execution of the program the shared Qt-libraries would be sufficiant, but you are not there, yet. So make sure, that a recent version of Qt is installed on your system (version 4.7 is alright at the time of this writing).

Note: If you have already built other programs from source-code, you may be familiar with the so called autotools, which serve the same purpose to create a Makefile from a provided project-configuration. QMake is just Trolltech/Nokia's platform-independent way to do this.

Unzip the compressed program-archive. This will result in a new directory being created, probably named similar to FOPLaboratory_[version-number]. Access this directory in the terminal-application, that is available on your platform (a Shell in Unix-derivates, some DOS-like application in Microsoft-OSs).

The first step to create an executable program from the sources is to run the QMake-utility right there in the uncompressed project-directory. QMake will find the project-file FOPLaboratory.pro automatically and generate from its contents a Makefile, that is already adapted to the platform, that QMake is currently running on.

user@machine:~/ [PATH_TO_FOLAB]/FOPLaboratory_0.1$ qmake

make the program

Provided, that QMake did not report any errors, the Makefile is now created and if there are also a C++ compiler and the make-tool available, you can call make right away:

user@machine:~/ [PATH_TO_FOLAB]/FOPLaboratory_0.1$ make

The C++-compiler will be called to build the program from the source-files in the folder src.

The option clean to the make command can serve to clean the project-directory from all built files, possibly in preparation for a new build:

user@machine:~/ [PATH_TO_FOLAB]/FOPLaboratory_0.1$ make clean

Installation of the binary in the file-system

I am sorry to say that this, again, lies in your responsibility. The FOPLaboratory executable may be moved to the place, that is considered the right one on your operating system. Linux-users may like the use the PACO package management utility for the installation, as it keeps a list of all the changes done and thus allows a clean de-installation, once it becomes necessary.

Install the tools

FOP

A frontend to FOP can naturally only do some useful work, if FOP is installed on the same computer. If you have not done so, yet, get FOP from the download-page at Apache.org or, -when you use Linux-, install it with the package-management software which came with your distribution.

Tidy

As FOPLaboratory allows you to open, create or modify XML- and XSL-files in a simple editor, there should be a way to verify and possibly beautify the xml-structure of such a file. Rather than programming myself all the clever routines for this task, I provide the option to call the tidy-utility as an external program, just like with FOP itself.

To install tidy, either have a look at the software which is offered by your Linux-distribution or go to the tidy-homepage at sourceforge. For Microsoft Windows™ you may find a recent binary executable version of the tool. For Linux it may be necessary to compile Tidy from the source-code, if you cannot find it in the packages of your Linux-version. But that is highly improbable.

Do not worry about the release-dates of the tidy-utility. Its use is of such a general nature, that updates are not as frequent as with other software that you may know. Even the most recent changes to the program are of such minor effect, that you could just as well use much older releases.

Introduction

Apache FOP

If you know Apache FOP, you can probably skip this chapter. Otherwise click on the this text to open it.

The Apache FOP XSL/FO processor is used to transform the contents of one or more XML input files into a new document of one of the supported types:

How the resulting document is formated is defined in an XSL/FO style-sheet and thus kept independent of the data and the final document-type. Put another way, the same input can repeatedly be transformed into different documents, by use of different style-sheets or, -by use of the always same style-sheet and formatting-rules-, into documents of different output-type.

It rests with the developer of the style-sheet to decide in which way the original data will be best presented.

Oftentimes, the final transformation into PDF or other formats is triggered by a programmed software-system; and most of the time this is the same system which has generated the original XML-data, too. The reasons for this indirect production of output are manifold, for example:

and so forth...

In such cases, the fo-processor is integrated in the program which is calling it.

However, Apache FOP comes with an executable binary file, that can be executed to transform just any XML-file into a more human-readable, formatted document, provided that there is also an XSL sheet available for the purpose.

You should, at least once, call the fop executable without any arguments in your command-interpreter. The program will then present you its usage information with all the possible options and a concise explanation of their purpose

user@machine:~$ fop
FOP Version 1.0

USAGE
fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl|-ps|-txt|-at [mime]|-print] <outfile>
[OPTIONS]  
  -version          print FOP version and exit
  -d                debug mode   
  -x                dump configuration settings  
  -q                quiet mode  
  -c cfg.xml        use additional configuration file cfg.xml
  -l lang           the language to use for user information 
  -r                relaxed/less strict validation (where available)
  -dpi xxx          target resolution in dots per inch (dpi) where xxx is a number
  -s                for area tree XML, down to block areas only
  -v                run in verbose mode (currently simply print FOP version and continue)

  -o [password]     PDF file will be encrypted with option owner password
  -u [password]     PDF file will be encrypted with option user password
  -noprint          PDF file will be encrypted without printing permission
  -nocopy           PDF file will be encrypted without copy content permission
  -noedit           PDF file will be encrypted without edit content permission
  -noannotations    PDF file will be encrypted without edit annotation permission
  -a                enables accessibility features (Tagged PDF etc., default off)
  -pdfprofile prof  PDF file will be generated with the specified profile
                    (Examples for prof: PDF/A-1b or PDF/X-3:2003)

  -conserve         Enable memory-conservation policy (trades memory-consumption for disk I/O)
                    (Note: currently only influences whether the area tree is serialized.)

 [INPUT]  
  infile            xsl:fo input file (the same as the next) 
                    (use '-' for infile to pipe input from stdin)
  -fo  infile       xsl:fo input file  
  -xml infile       xml input file, must be used together with -xsl 
  -atin infile      area tree input file 
  -ifin infile      intermediate format input file 
  -imagein infile   image input file (piping through stdin not supported)
  -xsl stylesheet   xslt stylesheet 
 
  -param name value <value> to use for parameter <name> in xslt stylesheet
                    (repeat '-param name value' for each parameter)
 
  -catalog          use catalog resolver for input XML and XSLT files
 [OUTPUT] 
  outfile           input will be rendered as PDF into outfile
                    (use '-' for outfile to pipe output to stdout)
  -pdf outfile      input will be rendered as PDF (outfile req'd)
  -pdfa1b outfile   input will be rendered as PDF/A-1b compliant PDF
                    (outfile req'd, same as "-pdf outfile -pdfprofile PDF/A-1b")
  -awt              input will be displayed on screen 
  -rtf outfile      input will be rendered as RTF (outfile req'd)
  -pcl outfile      input will be rendered as PCL (outfile req'd) 
  -ps outfile       input will be rendered as PostScript (outfile req'd) 
  -afp outfile      input will be rendered as AFP (outfile req'd)
  -tiff outfile     input will be rendered as TIFF (outfile req'd)
  -png outfile      input will be rendered as PNG (outfile req'd)
  -txt outfile      input will be rendered as plain text (outfile req'd) 
  -at [mime] out    representation of area tree as XML (outfile req'd) 
                    specify optional mime output to allow the AT to be converted
                    to final format later
  -if [mime] out    representation of document in intermediate format XML (outfile req'd)
                    specify optional mime output to allow the IF to be converted
                    to final format later
  -print            input file will be rendered and sent to the printer 
                    see options with "-print help" 
  -out mime outfile input will be rendered using the given MIME type
                    (outfile req'd) Example: "-out application/pdf D:\out.pdf"
                    (Tip: "-out list" prints the list of supported MIME types)
  -svg outfile      input will be rendered as an SVG slides file (outfile req'd) 
                    Experimental feature - requires additional fop-sandbox.jar.

  -foout outfile    input will only be XSL transformed. The intermediate 
                    XSL-FO file is saved and no rendering is performed. 
                    (Only available if you use -xml and -xsl parameters)


 [Examples]
  fop foo.fo foo.pdf 
  fop -fo foo.fo -pdf foo.pdf (does the same as the previous line)
  fop -xml foo.xml -xsl foo.xsl -pdf foo.pdf
  fop -xml foo.xml -xsl foo.xsl -foout foo.fo
  fop -xml - -xsl foo.xsl -pdf -
  fop foo.fo -mif foo.mif
  fop foo.fo -rtf foo.rtf
  fop foo.fo -print
  fop foo.fo -awt

Example

A previous version of this very page, that you are reading, has been processed with FOP, to create a PDF-version of the text:

The result
a PDF-file. Please note, that the HTML5-based PDF-Viewer extension to the Firefox-browser is faulty and its way of presenting the file is not authentic. Rather use an external PDF-viewer like Acrobat™-reader or Evince.
The XSL-FO style-sheets.
xhtml2pdf.xsl, folab.xsl. In FOPLab, only folab.xsl is entered. It includes the other file, which contains the general templates.
Most problems arose from the inconvenient way, in that FOP requires us to define the bookmark-tree, which will become the tree-like table of contents in the sidebar of your PDF-reader. I wanted this code to be flexible enough to process various XHTML-files as expected. Unfortunately, examples for the bookmark-tree that I found on the web, use static references (i.e. the verbose title of a bookmark) most of the time. And the fact is quite understandable. Without wishing to go into details, this was a real chore, as things which should be evident turned out to be quite simply impossible.
The original XHTML-file
Well, it is actually this file, you are currently looking at.

FOPLaboratory, as graphical user-interface to FOP

The main window

When you execute the FOPLaboratory program-file, you will see the following window: main dialog

This is the main program window in the English locale, the default.

For the most simple task to create a PDF-file from an original XML-file by use of a XSL/FO style-sheet especially created for the purpose, this interface has all you need. Enter the path to the XML-file in the upper field, the path to the style-sheet in the middle and name an output-file in one of the next two fields. Activate the pdf- or the fo-output, according to your needs. The buttons to the right of each input-field let you perform the following actions:

crayon Open the named file in the configured editor (integrated or external). The editor will be explained further down on this page.
eye Open a PDF-file in an external reader-application, if you have named one in the progam-options.
A fo-file will instead always be opened in an editor. In theory you can alter the file there, but these changes are of no effect to FOPLaboratory. The fo-file shall give you some insight in the way, that FOP will create its final output. It is not meant to be further processed with FOPLaboratory. If you wish to do so, call FOP directly on a command-line.
file Browse the file-system for a file or the directory to put the PDF-file in.

To start the transformation, click on the Go-button and wait a moment.

main dialog during transformationFor the duration of the transformation-process, some GUI-elements are disabled and change color. When they become active again, the PDF-file has been created or an error-message will pop up.

You can push the stop-button anytime to interrupt a running FOP-process.

Move the mouse over one of the buttons to see a toltip, describing its function.

input errorThe tooltip of the input-fields changes when you actually type in values. An invalid file-path will be signaled by red color and a tool-tip, like in the screen-shot to the right:

To enable the Go-button again, it is necessary to enter correct values in all three fields.

Attention: All values, that you enter, will be persisted when you quit the program. The next time when you execute FOPLaboratory, the previous values will automatically be entered again.

The options-dialog

In the main window click the button Options, to see the following dialog: Options-dialog

The configuration options are organized in tab-cards.

When you click the button Save on any tab-card, all your options-settings will be persisted and re-used the next time, that you start FOPLaboratory. The other button Close will not savethe configuration but close the options-dialog without taking into account any pending changeson any tabcard.

The program will do some verifications on the entered values and indicate problems, in case that e.g. file-names are invalid or values are entered in the wrong format.

FOP-Options

These options let you take an influence on how the FO-transformation is executed

Name the path to the fop executable file in the first input-field. This is useful, when either more than one version of the fop-processor is installed or the program is installed in a directory different from those, included in your PATH-variable.
If you leave this entry empty, the executable file fopis looked-up in the PATH-directories.

The second text-field can be either empty or contain the path to an xml-file with more configuration-options to fop. The possibilities and format-rules for this file are explained on the Apache XML-Federation web-site. In the sub-folder examples you find an exemplary version of this configuration-file (see screen-shot).

Optionally set the path to a PDF-viewer application. This allows you to open a finished PDF-document directly from the main-dialog ( see above). If you use Linux, the installed PDF-viewer may depend on your distribution and preferred window-manager. Possible choices are /usr/bin/okular(KDE) or /usr/bin/evince(Gnome). In Windows™ you will probably enter the path to the Adobe™ Acrobat-reader

The other two values will define, where the standard- and error-output of FOP will be directed. Choose a file-name for the standard- and one for the error-log.
When you leave one or both of these fields empty, two files in the currently set tempfolder will be used automatically. Both are created, if they do not yet exist. You can also set the same file for both types of output.

If they already exist and content is left over from the previous FO-transformation, you can directly see the current logs by clicking one of the View buttons. The logfile-viewer ( see below) will then open and display the content of the chosen file.

Editor options

On this tab-card you can:

screen shot

When the internal editor is selected, click on a field in the middle section of the window. Another dialog will show up, where you can choose how an xml-element shall be highlighted in the text-editor (next screen-shot).

screen shot

Apart from the default-setting which is applied to text-nodes, you can alter fonts and colors for XML-tags, -attributes, attribute-values and XML-comments. A click on the Default button will apply hardcoded standard-formats to each of the XML-elements and the previous settings will be lost.

In the lower section of the options-window and if you have selected the internal editor, you configure the tidy utility. Provided that the program is installed on your system, tidy can verify the format of any xml-file, directly from the integrated editor. While verifying and possibly correcting xml-code, tidy can also indent a file-content according to its xml-structure. screen-shot

The following options are offered to control the tidy-tool:

-i
tidy will indent the xml-code to mirror the structure of the data.
-m
Tidy will write back the modified content to the same file. Pay attention to the fact, that the previous version would normally be lost. In case of errors during the execution of tidy, I chose instead to write back the currently visible text from the editor to the file.
-utf8
Tidy will expect the original xml-content to have a UTF-8 encoding and also use this for the new version of the file, if the option -mwas also chosen.
-w [number]
Tidy will enforce lines to be wrapped after this many characters, if also the -moption was chosen.

You can switch off tidy completely by unchecking the first check-button. The last check-button allows you to refer to an external configuration-file to fine-tune the behavior of the tool. However, this option is more interesting, when you wish to validate HTML- or XHTML-code. A frugal XML-file does not require more options, than those present in the dialog. See the examplary configuration-file in the sub-folder examples.

With the selection of an external editor, the choice of options is reduced and may even exclude the terminal-emulation under Microsoft™-Windows. screen-shot

When you change your XML- or XSL-files in an external editor, tidy can be called on the command-line, like in the following example:

user@machine:~/ [PATH TO THE XML FILE]$ /usr/bin/tidy -i -m -w 120 -utf8 -xml [file.xml]

Messages will be printed directly in the shell or command-interpreter and in case of success, the file will have been indented, wrapped and saved. In the Vi- or GVim-editors, you can launch tidy without leaving the editor. Just change into command-mode (type a colon ':') and enter the command with a leading exclamation-mark ('!'). The current file will be represented by the percentage-symbol ('%'). Example: tidy command in GVim

The log-file viewer

In the main window, click on the button Logsto see the output from the most recent transformation-process.

log-file viewer

By default, the dialog will show you the the standard-output of FOP. You can mark the radio-button Error logto see the output to the error channel instead.

The log-files will be overwritten with each transformation. The refresh-option was meant to keep track of the current events by re-loading the log-file frequently during an ongoing transformation. This does not seem to work and the option shall be removed in one of the next program-versions.

The integrated editor

To allow quick modification of the files which are participating in the transformation, but also adaptations to the tool-configurations, a simple editor is integrated in FOPLaboratory. It is accessible by clicking one of the edit buttons, showing a crayon-symbol.

screen-shot

The syntax-highlighting feature is configured in the options-dialog, as explained above. In the editor you can do the following things:

The context-menu (right-click-menu) of the editor contains commands copy&paste text but also to find expressions in the document once or repeatedly.

Configuration-file

(Linux only)

Under Linux, the configuration-files are located in a hidden folder .config in the user's home-directory. Authors of programs may choose their own name or that of their company for the subfolder, where actual configuration-files are stored. The FOPLaboratory-program writes current option-values, window-settings and file-locations to
~/.config/Michael Uplawski/FOLab.conf

The settings from this file are automatically restored each time, that you start the program anew. It is normally of no use to alter these entries manually. Also, FOPLaboratory tries to avoid that false entries be persisted to the configuration, e.g. by awaiting a successful termination of a transformation-process, before it stores the current state.

However, there is no big risk in opening the file to get an overview of its contents. Should anything go wrong, you can even remove the file completely. FOPLaboratory will re-create it from scratch. But of course, in this case you would have to enter again all your preferences in the FOP- and editor-options.

Objective

FOPLaboratory should facilitate the repeated transformation of one and the same XML-file to PDF. Its main feature is therefor the capability to restore the configuration of one transformation job for a later run. When XML-contents or the XSL style-sheet change, you can just execute FOPLaboratory and immediately start processing to create an updated PDF-file.

On the other hand, FOPLaboratory lets you swiftly exchange XSL-sheets to generate different PDF-files from one and the same XML-contents.

With version 0.3 I introduced a simple editor to perform modifications in the XML-, XSL or configuration-files directly from FOPLaboratory. By integrating the tidy-tool, your files can be checked for XML standard-conformance. This means, that now practically all the preparatory work for the XSL/FO-transformation can also be done directly in FOPLaboratory. However, the editor does not replace applications like Kate, Ultra-Edit or full-blown XML-editors and might be removed again in future versions of FOPLaboratory.

In the Queue

This means, that new options can be selected and more values can be stored with FOPLaboratory for re-use in subsequent transformations.


2011 Michael Uplawski email address
Creative Commons License This document describing the FOPLaboratory-program,
is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.