JPdfBookmarks Manual

by
Flaviano Petrocchi
JPdfBookmarks Manual _______________________________________ 1
Introduction _____________________________________________________ 3
Installation and Uninstallation ______________________________________ 4
Linux Instructions ____________________________________________________ 4
Debian Instructions ___________________________________________________ 6
Windows Instructions _________________________________________________ 6
Universal Archive Instructions ___________________________________________ 7
Command Line Mode _____________________________________________ 8
Insert Bookmarks ____________________________________________________ 9
Extract Bookmarks __________________________________________________ 10
Graphical User Interface Mode ____________________________________ 11
PDF Bookmarks ____________________________________________________ 12
Fit Width_________________________________________________________ 12
Fit Page _________________________________________________________ 12
Fit Height ________________________________________________________ 12
Set Top and Left Offset _____________________________________________ 13
Destination Unknown _______________________________________________ 14
Bookmarks Appearance ______________________________________________ 15
How to Create Bookmarks ____________________________________________ 16
How to Modify or Cancel Bookmarks ____________________________________ 17
How to Modify Multiple Bookmarks ______________________________________ 18
How to Use Rulers __________________________________________________ 19
How To Reorder Bookmarks ___________________________________________ 20
License _______________________________________________________ 21
Author Information ______________________________________________ 22
Introduction
JPdfBookmarks is an utility program to create or edit bookmarks on existing PDF files. It is
not a pdf viewer so you need to use it in conjunction with a pdf viewer of your choice like
Adobe Reader or kpdf or whatever you like. It has a command line and a graphical
interface. You can create different kind of bookmarks, not pointing only at top of page but
also at different positions within the page, using fit page width , fit page height or fit whole
page options. Bookmarks can be reordered by dragging them around with the mouse.
The reference site for this software is my blog, visit it to download latest version and leave
comments to signal bugs or just to tell me you are using my software.
This software requires Java Runtime version 5 or above, you can check if you have it
already and eventually obtain the latest runtime at www.java.com.

You can download it also on softpedia for both Windows and Linux.
Installation and Uninstallation
JPdfBookmarks is a java software, so it is intrinsically cross-platform, anyway it is
packaged differently for Linux and Windows to make installation easier, while other OS
users can use the universal zip archive.
To download the appropriate latest version follow this link.
This section contains detailed instructions on how to install and uninstall JPdfBookmarks
on different platforms.

Linux Instructions
The preferred way to install on Linux is by using the packaged Linux installer from the
Download page at my blog. If you have installed an old version please uninstall it before
upgrading to the new one. You can do this by launching the uninstall program which is
inside the installation folder of jpdfbookmarks, this must be done as root user, so double
click the uninstall program from a File Manager opened as root or open a terminal inside
the installation folder, become root and type the command:

To use the Linux installer give the downloaded file execution permissions, this can be done
right clicking on it and choosing properties on most desktop environments
or with the command:

After this launch the installer by double clicking it in the File Manager or launch it in the
terminal with the command:

You will be prompted for the root password and then you will be asked for the folder where
to install the program, the default folder is /usr/local/lib/jpdfbookmarks.

Now you should be able to execute the program by command-line or by clicking the
shortcut in the main menu:
If this doesn't work read on for some details that can help you to solve the problem.

The installation process extract all the needed files in the chosen directory, then create a
symbolic link called jpdfbookmarks in the /usr/bin folder pointing to a launch script in the
installation directory called target_executable.sh. Actually this link is what you execute
when you type jpdfbookmarks in a terminal or when you click on the program launcher in
the main menu. So what you should check first if something is not working is whether you
have the file /usr/bin/jpdfbookmarks or not. If you don't have it you can try to create it
manually. If you have it the problem could be that the directory /usr/bin is not in your PATH
environment variable, try to add this folder to your PATH. Another problem can be that you
don't have installed in your system a couple of utilities that the target_executable.sh script
uses, which are "readlink" and "dirname". The installation directory also contains a launch
script that you can use from a terminal with the command ./jpdfbookmarks but only from
inside the installation directory, The last solution is to launch the program from inside the
installation directory with the command java -jar jpdfbookmarks.jar.

Debian Instructions
If you have Debian or one of its derivative, you can use the .deb package available at the
Download page in my blog, I recommend to use gdebi to install it because it will resolve
dependencies installing the java runtime if necessary:

# gdebi jpdfbookmarks_1.2.3_all.deb

otherwise you can use dpkg:

# dpkg -i jpdfbookmarks_1.2.3_all.deb

You must run the above commands as root.

If none of these methods work read the Universal Archive Instructions or post to my blog
and i will try to help you.

Windows Instructions
The preferred way to install on Windows is by using the packaged Windows installer
downloaded from the Download page at my blog. If you have installed an old version
please uninstall it before upgrading to the new one. You can do this by activating the
shortcut in the main menu program folder or by using the control panel applet.

After the download simply double click the setup executable and follow the installation
steps prompted. To launch the program with the graphic user interface use the shortcuts
on desktop or in the main menu. If you need the command-line functionality you can use
the program jpdfbookamrks_cli.exe in a command prompt window, from any directory
because the installer adds the installation directory of jpdfbookmarks to your PATH
variable:
jpdfbookmarks_cli.exe <arguments>

Universal Archive Instructions

If you are not using Linux or Windows (or if you have problems with their installation
packages) you can use the universal zip archive downloaded from the Download page at
my blog. After the download unzip the archive in a position of your choice, inside the
program folder the main program executable is represented by the file jpdfbookmarks.jar,
which in many systems is already associated with the java virtual machine and you can
execute it by simply double click it in a File Manager, if this is not your case you can run it
on any system with the command:

java -jar jpdfbookmarks.jar

Inside the folder you can find also a bash shell script to launch the program for the
systems that can use bash. Before you can launch it give it execution permissions with the
command:
chmod +x jpdfbookmarks

then you can use it from a terminal inside the folder with the command:
./jpdfbookmarks

In th folder there is also another scrip that is called target_executable.sh, which is again a
bash script created to launch the program from a symbolic link to it, to use it give it
execution permissions with:
chmod +x target_executable.sh

then create a link to it in a directory in your PATH environment variable, on my system a

command like the following typed as root do the job:
sudo ln -s /usr/local/lib/jpdfbookmarks/target_executable.sh /usr/local/bin/jpdfbookmarks

now you can launch the program from any terminal simply typing jpdfbookmarks.

I have also included in the folder the Windows exe launcher for the windows users that
don't want to use the installer, you can simply double click it to launch the application.

To uninstall any older version simply erase the old unzipped folder.
Command Line Mode
You can use jpdfbookmarks by command line to extract or insert bookmarks in a pdf. To
launch the application in command line mode you must use the appropriate method for
your system and the append the arguments described in the following sections, consult the
Installation Instructions section to understand which is the appropriate way for you. I will
refer to the launch command with jpdfbookmarks in these instructions but consider that
maybe you have to substitute it with jpdfbokkmarks_cli.exe , java -jar jpdfbookmarks.jar or with
./jpdfbookmarks for example.

To print a help message in a terminal use the command:

jpdfbookmarks --help
Insert Bookmarks
To insert bookmarks in a pdf file first you have to create a simple text file which will
represent the structure of your bookmarks using your favorite plain text editor, each line of
text is a bookmark item written in the form:

Chapter 1. The Beginning/23

Para 1.1 Child of The Beginning/25,FitWidth,96
Para 1.1.1 Child of Child of The Beginning/26,FitHeight,43
Chapter 2. The Continue/30,TopLeft,120,42
Para 2.1 Child of The Beginning/32,FitPage

where the part on the left of the '/' character is the title of the bookmark and the part on the
right is the target page of the bookmark. The page number is optionally followed by comma
separated values, the first parameter is the fit type used for the bookmarks. If this type is
TopLeft then other two parameters are necessary, the top and left offsets in thousandths of
the page height and width (zoom factor will be inherited), if the type is FitWidth only the top
offset is necessary while if the fit type is FitHeight only the left offset must be specified.
The type FitPage doesn't need any other parameter. If no parameter follows the page
number then FitWidth is assumed with no offset. Text indentation represents the hierarchy
of the outlines and must be obtained with "tab characters" (spaces will not work). Once you
have the file, save it to the same folder where you have the pdf file it refers to with a name
like bookmarks.txt, then assuming that the original pdf name is input.pdf and that we want
to save modified pdf as output.pdf, launch the command:
jpdfbookmarks --apply input.pdf bookmarks.txt output.pdf

If output.pdf already exists or if you indicate input.pdf as output file, the program will print a
warning and ask for confirmation before overwriting, i suggest that you never overwrite
existing files to avoid data loss.

Starting from version 1.2.3, you can apply the bookmarks from a text file using the
graphical user interface, from the Tools menu select the "Load Bookmarks" command and
choose the text file that contains the bookmarks structures

Warning: all the existing bookmarks in the original pdf will be lost with this
command!
Extract Bookmarks
If your pdf file already has bookmarks you can extract them to a text file that you can then
edit and reuse for inserting bookmarks. The command to extract bookmarks to a text file
is:
jpdfbookmarks --dump input.pdf > bookmarks.txt

Starting from version 1.2.3, you can dump the bookmarks to a text file using the graphical
user interface, from the Tools menu select the "Dump Bookmarks" command and choose
the text file where to save the bookmarks structure.

Warning: this command extract no information on color or style of the bookmark!

Graphical User Interface Mode
To launch the program with the graphical user interface simply use the shortcuts created
by the installation process in your main menu or desktop, if instead you are using a
terminal to launch it simply don't pass any argument to it, or if you want to pass a pdf file to
open at startup use the syntax:
jpdfbookmarks --gui file.pdf

or:

jpdfbookmarks file.pdf

In this section we will explore the possibilities offered by the program to create different
kind of bookmarks or modify existing ones.
PDF Bookmarks

Pdf file specification supports many types of bookmarks, pointing to one of the pages of
the document is only one of the possibilities (the only that jpdfbookmarks supports), other
kind of actions you can activate using them, range from opening another pdf document or
web document to playing a media file. In this sub-section I will briefly describe the various
kind of bookmarks you can create using jpdfbookmarks.

Fit Width

This is the most common bookmark for pdf files representing books, and is the default type
in jpdfbookmarks. When using this target type you will point to a particular page in the
current document and you will be able to see the entire page width in the pdf reader of
your choice. You can specify an offset from the top of page to point to a particular position
in the page (for example to the beginning of a paragraph ). In jpdfbookmarks offsets can
be specified in thousandths of the page extension in a particular direction, so if you want to
point to the middle of the page you have to specify a top offset of 500. To be more precise i
recommend the use of the top ruler, for instructions on how to use it read the relative
section. Another option is to inherit the top offset from the previous bookmark, I don't find it
very useful but try to experiment with it if you want. Obviously with this kind of bookmark
the left offset setting is not available and is disabled in the dialog.

Fit Page

When using this target type you will point to a particular page in the current document and
you will be able to see the entire page in the pdf reader of your choice. With this kind of
bookmark the top and left offsets have no meaning and the relative controls are disabled.
This can be useful for example when your pdf contains slides from a presentation and you
want to show the entire slide.

Fit Height

When using this target type you will point to a particular page in the current document and
you will be able to see the entire page height in the pdf reader of your choice. You can
specify an offset from the left margin of a page to point to a particular position in the page,
useful especially for large pdf pages in the horizontal direction. If the page is not larger
than the viewer width you will not notice the left offset, but it will be there, try to narrow the
viewer width and then reselect the bookmark to see the effect. In jpdfbookmarks offsets
can be specified in thousandths of the page extension in a particular direction, so if you
want to point to the middle of the page you have to specify a left offset of 500. To be more
precise I recommend the use of the left ruler, for instructions on how to use it read the
relative section. Another option is to inherit the left offset from the previous bookmark, I
don't find it very useful but try to experiment with it if you want. Obviously with this kind of
bookmark the top offset setting is not available and is disabled in the dialog.
 Set Top and Left Offset
This type of target point at specific coordinates in the page, the zoom factor is inherited
from the current setting of the reader. This is useful when you have very large pdf pages
(like maps) and you want to make bookmarks pointing to specific locations in the page. I
have also seen that a lot of tools use this type of target when generating bookmarks for pdf
files, I think this is to let the user choose a zoom factor that permits him to read the page
comfortably and still have their bookmarks working properly, this is a valuable behavior. In
jpdfbookmarks offsets can be specified in thousandths of the page extension in a particular
direction, so if you want to point to the middle of the page you have to specify a top offset
of 500. To be more precise i recommend the use of rulers, for instructions on how to use it
read the relative section.
 Destination Unknown

The "Destination unknown" option is to indicate all the outlines already present in the pdf
that are not supported by jpdfbookmarks, meaning you cannot modify them but will be
maintained when you save the file. You can use this option for example to insert a
bookmark pointing to no page in the document but that is the father of other child
bookmarks.
Bookmarks Appearance
In jpdfbookmarks you can change the bookmark's title appearance, from the standard plain
and black, to the bold and/or italic style and to different colors using the dialog controls.

If you want that your bookmarks are shown as soon as the reader opens the file check the
"Show Bookmarks on open" check box in the toolbar.
How to Create Bookmarks
To create a new bookmark in a pdf you can use without distinction the toolbar buttons, the
context menu items or the edit menu items. If the pdf has no bookmark yet, you can create
the first top level bookmark with the "Add a Sibling Bookmark" button,

if instead the pdf already has some bookmark, you can use this button to create a new one
at the same level of the selected item in the tree. Same level means they have the same
father or they are both top level bookmarks.

The "Add a Child Bookmark" button,

is used instead to create a child bookmark of the selected item in the tree. For example if
the selected bookmark is pointing to "Chapter 1" you can use this button to point at
"Paragraph 1.1", first paragraph of the first chapter.

The default bookmark created will be a Fit Width bookmark pointing to the first page of the
document, read the next section to learn how to modify it.
How to Modify or Cancel Bookmarks
You can modify the bookmark title and the target page directly in the tree editing the text
representing it. You can start editing using the Edit voice in the context menu, in the edit
menu or pressing the "Edit" button,

Write the title you want and then the target page number after a '-' character,

Alternatively you can use the controls in the dialog on the right,

after any modification made using the dialog controls press the "Apply" button to register
changes or the "Reset" button to cancel them.

To Delete a bookmark use the "Delete Selected Bookmark" in the toolbar,

or use the menu item in the Edit menu, or in the context menu. This action delete the
bookmark and all its children so before applying this modification a confirmation dialog will
be presented.

How to Modify Multiple Bookmarks

If you need to make the same modifications to multiple bookmarks, you can select more
then one item in the tree holding down the "Control" key, then edit the attributes you want
to apply to all of them, don't matter about the others. Press the apply button and a dialog
will be shown, here you can check which attributes must be applied to all the selected
bookmarks the unchecked ones will be ignored, when finished press the "Apply to All"
button.

In the dialog to select which attributes to modify, there is an option to shift the pages of
each bookmark by a certain amount, positive or negative. This can be useful if you are
working on a pdf that is still growing or shrinking, now you are able to adjust the target
pages with a single action by adding or subtracting the number of pages inserted or
removed.
How to Use Rulers
The Top and Left rulers are a convenient way to precisely set offsets in bookmarks using a
pdf viewer of your choice in conjunction with jpdfbookmarks.

To use the rulers click on the Rulers buttons, they will open a new window with a ruler in it,
i will explain how to use the top ruler, the left one works the same in the horizontal
direction:
1. open the PDF with your reader of choice, i will use Adobe Reader, and go to the
page that is the target of your bookmark;
2. adjust the zoom to see the entire page height, on my screen 50% is ok;
3. align the first tick of the slider (corresponding to 0) with the start of the page;
4. extend or reduce the ruler window so that the last tick (corresponding to 1000) will
be aligned to the end of the page;
5. now move the slider indicator to the position where you want to point your bookmark
in the page and press the send button;

now you have precisely set the position where to point in the page and if you have set the
rest of options you can press the "Apply" button.

The rulers are configured to stay on top of all another windows but if you find this annoying
you can clear the "Always on top" check box.
How To Reorder Bookmarks
To move a bookmark from a location to another in the hierarchy you can drag and drop it
from one position to another, all its children will be moved with him so you can move only
up in the hierarchy or within the same level. If you drag a bookmark over the icon of
another bookmark, a gray line will show you where it will be dropped (before or after),
while if you drag over the text of a bookmark it will be dropped as the child of that
bookmark. If dragging you stop for a while on a collapsed node, it will expand giving you
the possibility to drop inside of it, if you stop on an already expanded node it will collapse
again. You can also scroll the tree moving out of its bounds while dragging if needed.

You can quickly expand or collapse all the bookmarks nodes using the keyboard shortcuts
CTRL+E and CTRL+P or using the menu items 'View->Expand All' and 'View->Collapse
All'.
License
Copyright © 2008 by Flaviano Petrocchi <flavianopetrocchi@gmail.com>. All rights
reserved.

Redistribution and use in binary form are permitted provided that the following conditions
are met:

1. Redistributions in binary form must reproduce the above copyright notice, this list of
conditions and the following disclaimer in the documentation and/or other materials
provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Notes:
This program uses PDFBox library whose license is in the lib folder.
Icons are from the Tango Project.
Author Information
Copyright © 2008 by Flaviano Petrocchi. All rights reserved.

E-mail: jpdfbookmarks@altervista.org; flavianopetrocchi@gmail.com

Author's Blog: http://flavianopetrocchi.blogspot.com/