FOPLaboratory Files

FOPLaboratory
=============
A GUI frontend to Apache-FOP.

****** FOPLaboratory ******

FOPLaboratory is free software under the GNU_General_Public License.

Copyright (C) 2011-2012 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)

                   Locale-specific translations, as they are read
                   by FOPLaboratory to show labels and other text
several files *.qm in other languages than English. There are
                   files for French and German locales, but the
                   French translation is not done, yet.

                   Translation-files in XML-format, allowing a
                   translator to add her/his own translation of
several files *.ts 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.
                   The project file defines the components of the

FOPLaboratory.pro  program, translations inclusive. It is read by
                   the QMake utility and needed to create the
                   Makefile.

license.txt        The Gnu_General_Public_license.

                   Contains an examplary XML-file, XSL style-
                   sheets and configuration-files to fop and
examples           tidy. One of the style-sheets is faulty to
                   demonstrate how FOPLaboratory reacts in such a
                   case.

images             Currently contains only a program-icon.

                   The FOPLaboratory source-code. Once a Makefile
src                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:
    * I do not know the requirements of anybody's operating
      system and also do not care to know.
    * By delivering the sources, I give you all you need to
      evaluate the quality of my produce prior use.
    * Prior compiling the code yourself, you will have to make
      sure, that all required libraries are already installed on
      your system. In case that the compilation fails, an error-
      message should give you a hint on the packages that are
      missing.

**** 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(TM) 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.

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:
    * PDF, Adope Portable Document format
    * PDF/A-1b, Unicode enabled PDF
    * RTF, rich text
    * PCL, HP Printer Job Language data
    * AFP, IBM Advanced Function Printing
    * Postscript
    * TIFF
    * PNG
    * Text

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:
    * the need to frequently adapt the formatting of printed
      reports, while the program itself shall not be modified,
    * a variety of uses for the same set of data or only specific
      portions of the data
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.

**** 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
      the PDF-file, that you find in the folder doc

  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
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:

         Open the named file in the configured editor (integrated
[crayon] or external). The editor will be explained further down
         on this page.

         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
[eye]    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.
For 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.
The 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 
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(TM) you will probably enter the path to the
Adobe(TM) 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:
    * Choose between the internal editor and an external editor-
      application. Afterwards, when you click any one of the
      buttons which show an crayon-symbol, the
      adjacently named file will be opened in this editor. The
      other two options will only have an effect, when you use
      the internal editor.

    * Adapt the color- and font-settings for the syntax-
      highlighting in the internal editor. This will have an
      effect, when you open xml- files, -including xhtml and xsl-
      stylesheets.

    * Optionally configure the tidy-tool for the verification and
      indentation of XML-files in the internal editor.

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.

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.

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(TM)-Windows.
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 ('%'). 

*** The log-file viewer ***

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

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.

The syntax-highlighting feature is configured in the options-
dialog, as explained above. In the editor you can do the
following things:
    * Navigate and alter text
    * Click the Save-button to save an altered text- or XML-file,
      including XSL or HTML-files.
    * Click the Save as...-button to write the current content to
      a new file.
    * Click the Reload-button to revert all pending (unsaved)
      changes and replace the text by the current content of the
      file.
    * Click the Options-button to access the editor-options,
      where you can adapt the syntax-highlighting. These changes
      will though become active only when you close and open the
      editor again.
    * Execute the tidy-tool to verify the well-formedness of the
      XML-code and to beautify the content.
    * Consult the tidy-logs after the validation to find detailed
      error-messages or warnings, in case that tidy has produced
      any.
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 ****

    * Xsl variables shall be defined in FOP-laboratory as if they
      where defined in the processed xsl style-sheet. This will
      allow to fine-tune the processing, e.g. when the style-
      sheet contains switches that react to such variables, or
      when you wish to exceptionally overwrite values, which are
      normally derived in a different way. There are several ways
      to implement this new feature and I have not yet chosen
      one.
    * Future versions of FOPLaboratory will probably no longer
      include the internal editor, as it appears to be not really
      helpful.
      Since version 0.5, a user may already choose an external
      editor-application to view and modify text-files. I
      implemented this feature after my own experience with the
      program and its integrated editor. The syntax-highlighting
      had to be frequently adapted, whenever I found new valid
      variations in my own XML- and XSL-code. It is clear that
      this is a task that others have accomplished much more
      elegantly and you should be free to choose the program that
      suits you best.
    * I want to integrate Pdftk and pdfopt in FOPLaboratory. In a
      later version it will then be possible to alter and set
      some of the document-properties like Author, Subject,
      Keywordsand to attach files to the PDF.

This means, that new options can be selected and more values can
be stored with FOPLaboratory for re-use in subsequent
transformations. Ω
=================================================================
This document describing the FOPLaboratory-program,
is licensed under a Creative_Commons_Attribution-ShareAlike_3.0
Unported_License.