| PDF editor pro UNIX / PDF editor for UNIX |
(
)
|
Table of Contents
List of Tables This document describes usage of PDFedit, how to install and run program and how to work in commandline or graphical mode (GUI). It also describes using and writing user scripts. Document itself is divided into several parts:
Pdf Editor is primary created for simple editation and manipulation with objects of documents in PDF format and storing them as new version of document. Editation and manipulation with objets is by graphical and by commandline interface too. For simple use command line is using script language, which is usefull in graphical interface too.
These libraries are required to build and install PDF Editor:
Modified version of qsa library (Qt Script for Applications), version 1.1.4 is included in the source tree We tested compiling with various g++ versions - 3.x and 4.x were fine, it may compile on older versions like 2.95, but it was not tested. Program uses extensively RTTI, so the compiler used to build the program must support it. For building kernel tests, you need to have CPPunit installed For rebuilding documentation from DocBook .xml files, gmake (GNU make) is required and you also need:
If some of the required dependencies is missing, documentation in appropriate format will not be generated. In distributed archive, HTML documentation is already generated. For rebuilding programmer reference, doxygen is required. Prerequisites.
Make sure you have all needed libraries (qt3, boost and xlib) along with their headers.
You also need the environment variable Configuration. First step is to run configuration script, it will do some checks of required libraries and environment. Also, it allow to alter default settings (which is that the application will be installed in /usr/local directory tree) In CVS root (or root of distribution archive) type ./configure [parameters] to run configuration
With parametr Compiling. After running configure, type make to compile PDF Editor and re-genereate documentation (if needed, in the distribution archive the documentation is already pre-generated in HTML format, if you have proper tools installed (xstlproc, apache fop), then PDF version of documentation is also generated, if not, it is simply skipped as it is not essential) Installing. In CVS root (or root of distribution archive) type make install to install PDF Editor. It will check whether the project is compiled (if not, it will compile it) and install the editor. Uninstalling. In CVS root (or root of distribution archive) type make uninstall to uninstall PDF Editor. The editor must be already built (and installed) for this to work. This will remove all the files that have been installed by make install Table of Contents All commandline parameters are also described on editor manpage, which is installed with the program. To see the manpage, type command: man pdfedit. Table of Contents You can specify any number of filenames as parameters on commandline. One window will be opened for each file specified. If no file is specified on commandline, editor will be loaded initially empty. Name of files can be mixed with options (parameter that begin with a dash). Invalid option on commandline will cause editor to abort with error message. Names of options are case sensitive.
Options which require a parameter can be specified in "short form", like
Use Set verbosity of debugging messages reported by editor. Only messages below or equal level specified in parameter will be shown, default is debugging level 1. Also, any of symbolic constants defined below (case insensitive), or starting part of them may be given instead of corresponding number. Table 1.1. Explanation of debugging levels
Setting this to -1 mean no debug messages will be shown at all, not even the most critical ones. Debugging messages are sent to STDERR. Run in commandline mode. No editor windows are opened and commandline init script is executed. Run script with given filename. Look for the script in script path. If not found, look for the script in current directory.
Run script with given filename, but unlike
PDF Editor is run in english language by default, but by setting environment variable Aside default english, these localizations are available:
Table of Contents
Window of PDFEdit is split to 5 basic parts : Menu, Toolbars, Command part, Page space and Objects tree + property editor.
Command console is useful for typing in your own scripts and macros. In can be set in 3 different modes of behavior (see settings of command console). You can type your script code in the lower part of the window (the commandline or script editor, depending on settings) and observe output of your commands in upper part (console) Table of Contents The page space displayes one page from opened document. Page number is shown at the bottom of displayed page, as is number of pages in document. On the right the actual position of mouse cursor on page in specified units is shown.  Page space design
There are two independent information in page space which must be actualized. First is the image of the page itself and information about page count. This part is updated only if someone calls script function go() because it can be very slow (to update page after each change could be a performance problem). Reload page button in toolbars and menu (and many other useful functions) call go() automatically. But direct changes in Object tree and property editor and changes using scripting do not update the page and page count automatically. The second is the mouse position on page. Position must be converted into internal coordinates. The position does not depend on zoom level or actual rotation of page. (If the text starts at position [x:6, y:7 cm] in 100% zoom the same position will be used to started the text in 200% zoom.) Notice: The most common way is to have the zero in the left-bottom edge of page and to have the maximum in right-top edge.
It can happen that after a zoom change the outer page space is not updated. To corret this call either script go() function or click the reload page button. Right click of a mouse displayes a menu which will be displayed near the cursor. You can choose from two functions
The latter one can be used only when a selection is already present. Both functions store portion of viewed page to an image file. Format of the image file is depending on the system and version of Qt. Save page as image stores actual viewed page to an image file. If only a part of a page is displayed, only the part of page is stored. Save selected area as image stores only selected area. If selected area is fragmented or has not a rectangle shape, then a bounding rectangle of selected area is sotred. If selected area is bigger then actual displayed part of page, storing area is cropped with same rectangle as page is cropped in Save page as image. Table of Contents The right side of PdfEditor consists of two main parts Object tree and Property editor. It can be further specialized to Selection and Stream windows. Pdf file consists of objects which form a tree-like structure. There are seven simple objects
and three complex
Object tree displays the tree-like object hierarchy starting at the most important objects and Property editor displays the contents of selected object in human readable form and allows editing the objects in raw form. There is one important object called content stream which consists of many small operators and their operands. Everything visible on a page is in these content streams. Pdf operators are the objects that contorl what is displayed on a page. The content stream is shown in Stream window in human editable form. Last tool used to display objects is the Selection window. When some operators are selected using selection modes, those operators are displayed in the Selection window.  Object tree, Stream, Selection and Property editor The purpose of these windows is to enable complete control over pdf objects and structure of a pdf file. It shows raw pdf objects in user friendly way with the possibility to traverse the objects using the tree like structure, select special category of operators and perform operation on resulting set, see exactly which operators were selected using graphical selection tools. It also allows editing raw objects which mostly requires knowledge of the pdf standard. We gain complete control over pdf file with this tool. It can be used for advanced editing that almost makes PdfEditor a pdf creator. With the description of operators, object type highlighting and object importance visualization this tool can be also used by normal users for simple but powerful editions. We can add and delete objects almost at will (some top level objects are just for more human readibility and can be neither deleted nor added.) There are three main objects in the object tree.
Catalog object is the start point of all objects. Any object can be reached from Catalog. Pages and Outlines are just shortcuts for special objects somewhere deep in Catalog object. This feature is for very advanced users. Object tree can be used to to add and delete objects, stream and selection to delete objects. User can choose the type of object which to add. Deletion of pdf operator operands is not allowed because in most cases the result would be an invalid content stream. The adding object feature can be used to create completely new pdf files. With the help of scripting, PdfEditor can be used as pdf creator. The advantage is that we can use arbitrary empty template pdf file created by any drawing tool and PdfEditor to add objects into it. The creation of pdf files containing text is limited because we do not support our own fonts only standard ones. There are two ways how to to open, close and select objects. We can use either mouse or arrows. Up/down is used to go one object above/below current and right/left is used to open/close complex objects. When an object is selected right mouse click opens a menu with operations we can perform on the object according to its type.  Mouse right click menu
We can add properties/objects using Insert key or clicking  Add button button and delete properties/objects pressing Delete key or clicking  Delete button button. Not always is adding and deleting possible. We can use multiselect to select more objects and to perform specific action on all of them. We can use this feature in all mentioned tools (Object tree, Selection, Stream). This can dramatically increase speed of editing.  Multiselect
There are many special objects. You can specify which of them to display and which not. And whether crucial objects should be locked to changes. In menu click Tools->Options and select Editor tab. In order to take effect reload the object tree.  Editor options In menu click Tools->Options and select Object tree tab. In order to take effect reload the object tree.  Object tree display options
Many pdf objects are compulsory or must contain required entries or have specified values. Incompetent manipulation with these objects can result in invalid pdf files or non predictable output. Therefore a mode is assigned to every property which indicates the importance of the property. There are
When mouse cursor is over a property the property mode is displayed as text in the status bar. Hidden, read only and advanced tincture property colour to blue, gray and red. It depends on the theme used.  Visualization of object mode
These settings are stored in mode.conf file which can be easily modified to match user own pdf skills.
Each pdf object has simple value or set of values which can be changed. Almost all pdf operators have operands which are normal pdf objects which can be changed. Implicit changing of object types is not allowed (e.g. integer object to string etc.) but this can be done by deleting and adding desired property type. When changing integer object only integers are accepted, when changing boolean values only true/false is accepted etc.  Editing a property When editing a reference number a dialog appears which verifies whether a pdf object with specified reference number exists.  Text selection
To make a change visible perform these steps
PdfEditor allows selecting specific operators easily using selection modes. There are two main object selection modes namely text selection and graphical object selection. The third way how to select objects is using multiselect which allows us to manually select more objects. Selection is very useful when performing an action on many objects (e.g. deleting...) When this mode is selected we can select only text objects.  Text selection
Note: TrueType fonts use pictures to draw letters and that makes it very difficult to compute the height of the letter. The height of a true type letter can be incorrect. When this mode is selected we can select only graphical objects. Many pdf creators are putting strange invisible graphical objects to page so sometimes it is difficult to select the right graphical object.  Graphical object selection
Page is drawn by executing operations which are equal to small changes. These changes are stored in content stream of a page. You can display these operations by clicking Pages->Page #->Stream # in Object tree. New tab is displayed which shows pdf operators and their operands.  Stream
As mentioned above, operators control what is displayed on a page. For advanced editing, it is crucial to be able to change them. For non advanced users the operator tags are not very intuitive so a human description of each operator is shown in the status bar.  Operator description
The definition of the operators is stored in operator.hint and can be edited freely. There many operators but only few worth changing manually. To allow fast search of these operators, operator modes were designed. After selecting one of the operator modes in Stream window, only those operators are shown. Currently there are four operator modes
 Operator modes
Table of Contents This chapter describes only default functionality available from menu and toolbars because it is very customizable and can very differ from release to release. Removing and adding new functionality is very simple.
 Default menu item File
File - description of items
 Default menu item View
View - description of items
 Default menu item Tools
Tools - description of items
 Default menu item Page
Page - description of items
 Default menu item Edit
Edit - description of items
 Default menu item Help
Help - description of items
Toolbars are shortcut for functions found either in menu, or by right clicking on specific objects. Menu items can be either in enabled or disabled state. Some operations have no effect when a document is not open so they are disabled. Also some operations are not avaliable when specific objects from specific windows are not selected.
 Toolbar - Main
 Toolbar - Page
 Toolbar - Selection Mode
 Toolbar - Draw
 Toolbar - Text
 Toolbar - Dynamic This toolbar contain dynamic items and its content is updated based on context, i.e. what are you doing now. It can contain field used to edit text in PDF operators or icons used to filter displayed operators in current stream. There are four modes available for filtering operators. First and default mode is to show all operators. The other three modes are to show only text, only font and only graphical operators. The filter settings are per stream, so you can set diffrnent filterig in different streams.
 Toolbar - Treeview When changing pdf file using Object tree, Selection or Stream tab we can add and remove objects using either keyboard or these two buttons.
 Toolbar - Revision When a document is changed it can be saved either as new copy, to old file or to new revision. The last option saves all changes made to the document. The history of changes is embedded in the document itself. We can choose which revision we want to have displayed. Only the last revision can be edited. Otherwise we have to save it before editing. Following functions are called from menu and toolbars and provide user friendly enviroment for simple editing. Modes in this section can be used to select objects on the displayed page. All modes support move and resize of selected objects, but the real functionality depends on implemented scripts, which perform real action with selected objects (e.g. moving nongraphical operators (text, pictures) and moving annotation activation rectangle, but moving graphical operators (line, rectangle, ...) is not implemented). When moving selected objects cursor must be in the selected region (cursor pointer will change to cross from arrows pointer). After pressing the mouse left button selection region can be moved. After releasing mouse left button script moving function is executed on the selected operators. When resizing objects cursor must be moved to the edge of bounding rectangle of selected region (cursor will change to two arrow oriented from each other direction - there are four possibilities how to resize: left-right, top-bottom, (left-top)-(right-bottom) and (left-bottom)-(right-top)). After pressing the left mouse button selected region is resized by cursor movement. Script function for resizing is executed when mouse left button is released. When cancelling started action press Esc key before releasing left mouse button. If Esc key is pressed during no action all objects on the page are unselected. This mode is usefull when selecting page objects (without annotations - see mode to select annotations) which are not text (see mode to select text) or graphical (see mode to select graphical operators) operator (line, rectangle, but not image). When this mode is activated,nonempty areas can be selected pressing the mouse left button, dragging the mouse and releasing left button. All objects within selected area will be selected. When clicked only once, the one top level object on the page is seleceted. If clicked again the second top most object is selected etc. User doesn't need to know the size of desired object. This mode is very usefull when because only few objects have the same size Object tree and property editor. To activate this selection mode just click on appropriate place in the toolbar toolbar Selection modes) or select it in menu (see menu item Edit). This mode is the same as mode to select all objects except for it only selects graphical operators. This mode is useful when selecting text on page. It behaves like expected from text selecting. Word and line order is respected on pages with horizontal text lines (most of pdf files). Text selection is very simple using this mode. The selection starts when mouse left button is pressed on a text element. (If the mouse is over a text element the cursor changes to ibeam.) When dragging, text is selected line by line. The selection is limited in how the text elements are stored in the pdf document (some documents have text elements equal to letters, to words, to lines or arbitrary). Note: When a text on one line is written using different fonts it is very likely that it will be parsed into more lines. This is due to the fact that the base vertical positions are different and without wild guessing it is almost impossible to distinguish between text on one with different fonts and text on more lines with different fonts. This mode displayes and enables selecting of annotations on a page. When activated each annotation is displayed as a rectangle (shows activation rectangle for each of annotations). It's very useful because user can see all the annotations on a page and does not need to search for (annotations can be hidden). Only very few viewers support this feature. An annotations is selected when the mouse cursor is over. It is selected until the mouse cursor get over another annotation or till Esc key is not pressed. Drawing lines is easy with this mode. First set default properties in the toolbar: foreground color, line width and dash style. Then by pressing the mouse left button and dragging a line is created. After releasing mouse button the line is drawn. The line drawn during dragging is only informative. The viewed part of the page is updated after each added line. To cancel line drawing press Esc key before releasing the mouse button. Drawing rectangles and rectangles with background is easy with this mode. First set default properties in the toolbar: background color. Then by pressing the mouse left button and dragging a new rectangle is crated. After releasing mouse button the rectangle is drawn. The rectangle drawn during dragging is only informative. The viewed part of the page is updated after each added line. To cancel rectangle drawing press Esc key before releasing the mouse button. This mode enables adding text lines onto the page. First set some default properties on the toolbar like foreground color, font and font size. Then by clicking mouse left button on page an edit box is shown where the added text is written. After pressing Enter the text will be displayed on the page. The viewed part of the page is updated after text addition. The text is added to the page also if the text edit line losts focus (this can be unpleasant for window managers that set focus to windows under the mouse cursor). To cancel text addition press Esc key. Note: When pages are rotated the text can appear unrotated. This is because the text uses own transformation matrix than the whole page. You can easily strike through words, lines with this mode. Selecting of text is the same as by mode to select text. After endind the selection scipt function is called which draws a line through selected text default colour, dash style and line width (for more details see mode to drawing line). Highlighting of text is a very desired feature. This mode can highlight selected text. After activating this mode user can select text the same way as by mode to select text. After ending the selection script function is called which draws filled rectangle under each text operator with default background colour (for more details see mode to drawing rectangles). Settings options in PDFEdit is very easy. Options can be set are in gui or directly in configuration file pdfeditrc in ~/.pdfedit and in PDFEdit home directory. If exist diferent setting for some option, is use setting in ~/.pdfedit/pdfeditrc. To execute options dialog in gui click to menu on Tools/Options. Or type to command console options(). Or click to options icon in toolbars. Execute options dialog from menu
Open files in advanced mode, allowing some more advanced,
but also potentially more destructive changes to be made to the file.
If checked, properties that are marked as hidden by configuration in mode.conf
will be shown.
If checked, properties that are marked as read-only by configuration in mode.conf
will be fully editable.
If checked, editor will remember path of last opened or saved file
and when opening or saving file, the dialog will start in that directory.
If unchecked, current directory is used.
This option allow to choose prefered length units.
These will be used for showing coordinates in the preview window and also
in some other places, like when editing size of the page.
You can set paths to various files here. The path is semicolon-separated list of directories,
each of them can contain environment variablesm, which will be automatically expanded,
such as
 In this tab you can specify what items will be visible in the object treeview.
This option toggles showwing of main document dictionary (called "document catalog") in tree.
This option toggles showwing of dictionaries of various objects (like pages) in tree.
The appereance of command editor can be customized in options dialog on tab "commandline". To execute options dialog click Tools/Options in menu or type options() in command editor or click the options icon in toolbar. 
If this setting is checked, command console will print return value of last command
after executing it. It has basically the same effect as if last command was a
parameter of function This will toggle displaying the return value for complex types, such as arrays, which are likely to produce lot of output, as arrays tend to be large. Check this if you want to see error from callback handlers. If there is error in callback handler which is called very often, like handler for current item in tree being changed, it can produce lot of output. If set, history is displayed in a combobox. This is useful when older history commands are needed. If set, editable command line is shown in history combobox. This is usefull when small space for typing command is needed. (set command editor hidden).
Each checkbox on this tab represent one toolbar in the program. You can toggle visibility of each toolbar here, if the checkbox before toolbar name is checked, the toolbar will be visible. If unchecked, the toolbar will be hidden.
 In this tab, you can select look and feel of the editor
Specify font used in application, in all components except console window and statusbar,
for which the fonts are set separately
Select icon theme used for icons in menus and toolbars. There are two predistributed icon sets,
default and hicolor. adding new set is easy, just add
subdirectory with your icons to any directory in icon path.
 Default icon theme  Hicolor icon theme PDFEditor have support for scripting. Evey item in menu (or toolbar) runs a script (mostly just short call of function, but using complex scripts from menu is possible), and also user can type script commands directly into commandline. Every invocation of script from menu will echo the command to the commandline, so user can learn how to do things in menu directly from commandline if he wants. QSA is used for scripting, which is based on ECMAScript standard (if you don't know what ECMAScript is, it is basically the same syntax as JavaScript) This documentation will not explain the language syntax, but will document all functions and objects that are exported from the application to the scripting engine so they may be used in scripts and menus. Also how the scripting work in general and how it can be configured will be explained.
NoteScripts are not "secure" by design, as the API contain functions to read or write arbitrary files and directories and to execute external processes. See http://doc.trolltech.com/qsa-1.1.4/extensions-2.html for description of File, Dir and Process classes, which are available to script.
When new editor window is launched (but before the document is loaded or created),
file
In commandline mode, file After running these init scripts, any "plugin" scripts from directories specified in configuration are run. By default, these directories are:
For "plugin scripts" in commandline mode, scripts are searched in Scripts are run in alphabetical order (by their filename, case sensitive) and if the same script is encountered in more than one directory, only the one in directory later in list is executed. This ensures that if user install newer version of some script in his home directory, only his version will get executed. After that, the document is loaded (if it was not specified on commandline, the window will be initially empty without any document) NoteInit script should not load a document while starting, as it will be replaced by new one as soon as the script finishes. If functionality such as "automatic loading of a document on startup" is desired, appropriate code should be added to onEmptyFile() function, which will be triggered after starting the editor with empty document. Alternatively, onLoad, onLoadUser or onLoadError fnuctions may be used for this.
|
