Main Page
From jpdfbookmarks
Contents |
Software Overview
This software allows you to create and edit bookmarks on existing PDF files.
Version Numbering System
The version numbering system is based on three numbers, at the time I am writing this the version number is 2.0.1, the last number (1) increases at every new release that correct bugs, the middle number (0) increases at every new release that adds new features, the first number (2) increases at every new release with major changes in how the program works. When first number changes backward compatibility could be broken (but this must not be always the case).
How Much is it Stable?
It is always difficult to say how much a software is stable, this would request a large number of beta testers which of course I don't have. When I make a new release it appears to me that is enough stable to be used without crashes and data loss in most cases, but bugs are surely present so I always recommend to make backup copies of the PDF files you modify with JPdfBookmarks. If this software is mission critical for you I would recommend caution, read the license carefully and evaluate if a commercial product with some sort of warranty is more appropriate for you.
Users Documentation
How to install and uninstall
I have decided not to provide installers any more, this is because I want to dedicate more time on development than on deployment, this could change in the future especially if someone else wants to help maintaining packages for specific platforms. For the time general purpose archives are distributed with binaries and scripts for all systems.
Download the zip or tar.gz archive of the latest version from source-forge (http://sourceforge.net/projects/jpdfbookmarks/) and extract the folder jpdfbookmarks-x.x.x to a position on your drive. Inside that folder you have both the windows executables and the Linux scripts to launch the application.
IMPORTANT: this software requires a Java Runtime Environment version 6 or later for information on how to install one on your system, or to check if you already have it, go to http://www.java.com or search your system's software repositories.
On Linux
You should extract the folder in a path without spaces and check if the scripts have execution permissions and if they don't use the following command:
$ chmod +x jpdfbookmarks jpdfbookmarks_cli $ chmod +x link_this_in_linux_path.sh link_this_in_linux_path_cli.sh
The jpdfbookmarks and jpdfbookmarks_cli scripts are intended to be used from the installation folder, so supposing you have extracted the folder to /home/user/jpdfbookmarks and you are working in the folder /home/user/documents you can launch the program with the full path to the script /home/user/jpdfbookmarks/jpdfbookmarks --help
This is not particularly efficient so I suggest to create links to start the program in a folder on your PATH environment variable, for example as root go to the /usr/local/bin folder and launch the command:
# ln -s /home/user/jpdfbookmarks/link_this_in_linux_path.sh jpdfbookmarks
or
# ln -s /home/user/jpdfbookmarks/link_this_in_linux_path_cli.sh jpdfbookmarks_cli
Now you are able to run jpdfbookmarks from any position just typing in a terminal jpdfbookmars (for the GUI) or jpdfbookmarks_cli (for the command line).
To uninstall on linux just delete the extracted folder of the program and eventually delete the links you have created.
On Windows
To launch the graphical user interface of the program on Windows double click jpdfbookmarks.exe, the program can take the pdf file to open as an argument to facilitate shell integration. To use the program on the command-line use the other executable jpdfbookmarks_cli.exe, if you use often the command prompt I suggest you to add the jpdfbookmarks-x.x.x folder to the PATH environment variable, you can easily find instructions on how to accomplish this on the web.
To uninstall just delete the extracted folder and cancel the path to the same folder from the PATH environment variable if you added it.
Universal
For all the systems you can launch the program after you have extracted the folder with:
$ java -jar /full/path/jpdfbookmarks/jpdfbookmarks.jar
it's important to provide the full path to the jpdfbookmarks.jar file.
On many systems also double clicking on jpdfbookmarks.jar will work to launch the application.
How to execute
Here follows a short help on the jpdfbookmarks parameters.
usage: jpdfbookmarks <input.pdf> [--dump | --apply <bookmarks.txt> |
--show-on-open <YES | NO | CHECK> | --help | --version |
--out <output.pdf | bookmarks.txt> |
--bookmark <1,FitWidth,500>]
To launch the graphic interface invoke without parameters or pass a pdf file you
want as parameter. On Windows the command line program must be called with
jpdfbookmarks_cli.exe while the graphic interface must be called with
jpdfbookmarks.exe.
-a,--apply <bookmarks.txt> Apply bookmarks from the file bookmarks.txt to a
pdf file passed as argument and save it to a new
pdf file specified with --out output.pdf. The
encoding for reading the bookmarks.txt file can be
changed using the --encoding option.
-b,--bookmark <arg> Use this in GUI mode to open the pdf file on a
specific page, use the same format of the bookmarks
text file omitting the title and styles attributes.
For example the command 'jpdfbookmarks --bookmark
"1,FiWidth,500" file.pdf' will open file.pdf at the
first page with a zoom to fit the width of the
viewer and scrolled to half page.
-d,--dump Extract bookmarks from a PDF file passed as
argument and print them to standard output or to a
file indicated with the option --out. The encoding
for the text file can be changed with the option
--encoding.
-e,--encoding <UTF-8> With this option you can read or write bookmarks
text file with the preferred encoding.
-f,--force With this option set the program doesn't warn if
you try to overwrite an existing file, use with
caution and backup your files.
-h,--help Print this message.
-i,--indentation <arg> String to use as indentation string (default value
is the tab character) , must be different from the
title and page number separator (default value '/')
and from the attributes separator (default value
',').
-o,--out <output.pdf> Used with the --apply option indicates the output
PDF file (--out file.pdf or -o file.pdf). Used with
the --dump option can indicate the output bookmarks
file (--out bookmarks.txt or -o bookmarks.txt), can
be used together with the --encoding option to
override the system default encoding of the text
file.
-p,--page-sep <arg> String to be use between title and page number
(default value is '/'), must be different from
attributes separator (default value ',') and from
indentation string (default value is the tab
character).
-t,--attributes-sep <arg> String to be use between the bookmark attributes
(default value is ','), must be different from the
title and page number separator (default value
'/') and from indentation string (default value is
the tab character).
-v,--version Version number.
-w,--show-on-open <arg> If you want to show the bookmarks as soon as the
pdf file is open pass YES to this option, if
otherwise you want to hide the bookmarks pass NO to
this option. To check what is the actual setting on
the file pass CHECK to this option and the program
will write to standard output YES or NO.
In the bookmarks.txt file each line is a bookmark and the hierarchy is made by tab characters (not spaces),in the format <Title of bookmark/target page[,FitType,TopOffset,LeftOffset] like the following example:
Chapter 1/23 [TAB]Para 1.1/25,FitWidth,96 [TAB][TAB]Para 1.1.1/26,FitHeight,43 Chapter 2/30,TopLeft,120,42 [TAB]Para 2.1/32,FitPage.
It is also possible to use an extended format to specify the text style, the color and the open or close state of the bookmark, like the following example:
Para 1.1/25,Red,bold,italic,open,FitWidth,96 or Para 1.1/25,Green,noBold,noItalic,closed,FitWidth,96
Supported Bookmarks Types
Pdf file specification supports many types of bookmarks, pointing to one of the pages of the document is only one of the possibilities, 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 kinds of bookmarks that jpdfbookmarks supports.
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. 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 ) or you can choose to inherit the current offset from the previous view.
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. This can be useful for example when your pdf contains one slide per page 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. You can specify an offset from the left margin of a page to point to a particular position in the page or inherit the offset from the previous view, this is useful especially for large pdf pages in the horizontal direction.
Top Left Zoom
This type of target point at specific coordinates in the page given in terms of offset from the top end left margins of the page, the zoom factor is the third parameter and give us the possibility to scale the page to a grater (positive) or smaller (negative) scale. Any of the parameters can be inherited from the previous view.
Fit Rectangle
This type of bookmark let us specify a rectangle of the page to be zoomed in the viewer. The smaller side of the rectangle will be used to calculate the zoom factor by the viewer so that the entire rectangle is always visible when activating the bookmark.
Named Destination
PDF files generated by automatic tools sometimes use destinations that have a name, so it is possible to use this name to create a bookmark pointing to that destination. JPdfBookmarks translates these named destinations to normal destinations that are easier to read and use by humans, but you can change this behavior in the preferences dialog if you need to work with named destinations directly.
Go To a URI
This kind of bookmark permits to create links to websites.
Go To Another PDF File
With this bookmark you can point to another PDF file in the file-system, jpdfbookmarks tries to use relative paths whenever possible but this is not always successful, so if you need a portable configuration of files make some tests with a compliant PDF reader.
Launch a File
This bookmark let you launch any file using the default application associated with it, for example if it is a text file on Windows it will be probably open in Notepad. Jpdfbookmarks tries to use relative paths whenever possible so that you can deploy directory of files that will continue to have valid bookmarks on different systems.
Bookmarks Text Format
Each bookmark in a PDF file can be expressed in the JPdfBookmarks format as a line of simple text like the following example:
Title of bookmark/3
this is the simplest representation of a bookmark pointing at the top of page 3, with a default zoom to fit the width of the viewer (FitWidth bookmark type). You can modify the type of bookmark adding it after the page number separated by a comma:
Title of bookmark/3,FitHeight
this will modify the zoom to fit the height of the viewer (FitHeight bookmark type). Now suppose you are happy with the FitWidth type but you want to point at half page instead of top, in this case you must explicitly write FitWidth after the page number and then put the top offset after a comma. JPdfBookmarks divides each page horizontally and vertically in thousandths units so that you don't need to know the exact measure of each page to assign a position to a bookmark, but you can just point at 500 to point to half page or 250 to point to the first quarter from top:
Title of bookmark/3,FitWidth,250
The FitHeight bookmark type can also accept one parameter which is the left offset in thousandths of the page width:
Title of bookmark/3,FitHeight,500
The PDF specification also permits to inherit the parameters of bookmarks from the current values, this is obtained in JPdfBookmarks using a parameter of -1:
Title of bookmark/3,FitHeight,-1
You can use the TopLeftZoom bookmark type using the format:
Title of bookmark/3,TopLeftZoom,500,250,2.0
where 500 is the top offset, 250 the left offset and 2.0 is the zoom factor (which can be negative to render the page at a smaller size), there is also a short variant if you intend to inherit the zoom factor:
Title of bookmark/3,TopLeft,500,250
The FitRect bookmark type instead takes four parameters that represents the position of the four sides of the rectangle (in the order top, left, bottom, right) to zoom in the viewer:
Title of bookmark/3,FitRect,50,50,500,800
The FitPage bookmark type takes no parameters. If you want to create a bookmark pointing at a web site use the Uri bookmark type:
Title of bookmark/-1,Uri,www.google.com
the page (-1) is ignored but must be there for the line to be parsed correctly by the program. To create a Bookmark to another PDF use the GoToFile bookmark type the syntax is:
Link to a PDF in a sibling folder/3,FitWidth,250,GoToFile,otherFilesFolder/file2.pdf Link to a PDF in the same folder/5,FitHeight,0,GoToFile,file3.pdf
To launch any file using the default application associated with it, use the Launch bookmark type:
Open the text file README.txt/-1,Launch,optionalFolder/README.txt
There is also the possibility to assign a color and a style to the bookmarks (but not all viewers honors these settings) and whether the bookmark must be opened or closed by default. These fields must be put after the page number and before the bookmark type indicator in the order color, bold/notBold, italic/notItalic, open/closed, all or none of these must be present, you cannot put only the color or only the bold style, 4 items must be there or none of them. As color you can use one of the browsers' known colors names (capitals matters so use Red and not red or BlueViolet and not blueviolet) or the hexadecimal RGB value after a # sign some examples:
Title/5,Red,bold,italic,open,FitWidth,250 Title/5,#00FF00,notBold,italic,closed,FitWidth,250 Title/5,CornflowerBlue,bold,notItalic,closed,FitWidth,250
To create a hierarchy in the bookmarks you can use tab characters to indent lines, be sure that your text editor doesn't substitute tab characters with spaces, unfortunately many editors have this default setting, look at the following example:
Chapter 1/1,FitWidth,300 Paragraph 1.1/3,FitWidth,450 Paragraph 1.2/5,TopLeft,200,50 Sub-Paragraph 1.2.1/7,FitWidth,150 Chapter 2/9,Black,bold,notItalic,open,FitWidth,250 Paragraph 2.1/11,Green,bold,italic,close,FitPage
Command Line Mode
JPdfBookmarks can be used as a command line tool to apply bookmarks to a PDF file or to dump bookmarks to the standard output (which you can easily redirect to a text file). To launch the application in command line mode you must use the appropriate method for your system and then append the arguments described in the following sections. I will refer to the launch command with jpdfbookmarks_cli in these instructions but consider that maybe you have to substitute it with java -jar jpdfbookmarks.jar or with ./jpdfbookmarks_cli.
To print a help message in a terminal use the command:
jpdfbookmarks_cli --help
How to Apply Bookmarks
First you have to create a text file containing the bookmarks hierarchy like described in the #Bookmarks Text Format section, then you can pass this text file to the --apply switch (short form is -a), the original PDF is passed without any switch before it and the position is not important (in the example is the first parameter), if you don't specify a destination file with the --out switch followed by a file name the bookmarks will be applied to the original file, I suggest to always use the --out option or to backup the original file before using jpdfbookmarks to avoid data loss, all modifications made by the program are irreversible, an example of command to apply bookmarks is:
jpdfbookmarks_cli original.pdf --apply bookmarks.txt --out modified.pdf
How to dump Bookmarks
To dump bookmarks already present in a PDF file use the --dump option (-d short form), it will print the bookmarks in the #Bookmarks Text Format to the standard output, use redirection to save the bookmarks in a text file, or better use the --out option followed by the text file name where you want to save the bookmarks to be able to specify an encoding (see section #How to resolve encodings problems). Examples:
jpdfbookmarks_cli file_with_bookmarks.pdf --dump jpdfbookmarks_cli file_with_bookmarks.pdf -d >bookmarks.txt jpdfbookmarks_cli file_with_bookmarks.pdf --dump --out bookmarks.txt
How to resolve encodings problems
Whenever you use text files in any program, encoding must be a concern and jpdfbookmarks is no exception. If you find strange characters in your bookmarks after using jpdfbookmarks probably you are applying bookmarks dumped or edited in a different encoding then the program expects.In these cases use the --encoding option followed by the name of the encoding you want to use, a list of possible encoding names can be found here. This option can be used both with --apply to let the program interpret correctly the text file containing the bookmarks, and with --dump to create a text file in the correct encoding you want, when used with --dump use also the --out option followed by the name of the bookmarks text file otherwise it will be ignored. For example under Windows the java virtual machine uses a different encoding in the command prompt than in the graphic programs so if you want to load bookmarks text files in the GUI that you have dumped on the console you probably will have encoding problems. Examples:
jpdfbookmarks_cli file_with_bookmarks.pdf --dump --encoding UTF-8 --out bookmarks.txt jpdfbookmarks_cli original.pdf --apply bookmarks.txt --encoding UTF-8 --out modified.pdf
How to Change Default Separators
The choice of using the tab character for indentation, the slash for the page separator and the comma for the other arguments was made to keep the text file as clean and readable as possible, but if you want you can change this values with something you think is more appropriate. The options are -i or --indentation followed by the string you want to use for creating the hierarchy instead of the tab, -p or --page-sep followed by the string you want to use for separating the title of the bookmark from the other parameters, -t or --attributes-sep followed by the string you want to use for separating the other parameters instead of the comma. Always use double quotes to enclose the strings passed as arguments to these options. The same changes can be done using a dialog in GUI mode accessible by the menu Tools->Options, the difference is that the command-line options are temporary, must be repeated at every execution and supersede the GUI options which are instead permanent. So if you make a change in GUI mode to some of the separators you will change also the separators in command-line mode, this was made to keep the use of the GUI and command-line synchronized so that one can dump bookmarks from GUI and apply from command-line or vice versa while still maintaining some flexibility.
Here is an example of dumping with different separators:
jpdfbookmarks_cli -i " >> " -p "|" -t ";" --dump book.pdf >bookmarks.txt
that will create the following bookmarks.txt file:
Chapter 1|1;Black;notBold;notItalic;closed;FitWidth;301 >> Paragraph 1.1|3;Black;notBold;notItalic;open;FitWidth;449 >> Paragraph 1.2|5;Black;notBold;notItalic;closed;TopLeftZoom;-11626;0;0.0 >> >> Sub-Paragraph 1.2.1|7;Black;notBold;notItalic;open;FitWidth;150 Chapter 2|9;Black;bold;notItalic;open;FitWidth;250 >> Paragraph 2.1|11;Green;bold;italic;open;FitPage
Of course when you want to apply the bookmarks back to the pdf you have to use the same options:
jpdfbookmarks_cli -i " >> " -p "|" -t ";" --apply bookmarks.txt --out modified.pdf book.pdf
If you find a configuration which is good for you I strongly suggest to use the GUI options dialog to change separators so that you don't have to type these options every time.
How to show bookmarks when PDF is opened
If you want that the bookmarks are shown as soon as the user opens the file in a compliant reader use the --show-on-open option (-w is the short form) followed by yes, if you don't want them to be shown by default follow the option with no. If you just want to know which is the current setting of the file follow the option with check and jpdfbookmarks will print YES or NO accordingly. Some examples:
jpdfbookmarks_cli input.pdf --show-on-open yes --out output.pdf jpdfbookmarks_cli input.pdf -w no -out output.pdf jpdfbookmarks_cli input.pdf --show-on-open check
Developers Documentation
How to build
My development environment is the JDK 6, I use the Netbeans IDE version 6.9.1 but you can build jpdfbookmarks on the command line using ant if you prefer. Netbeans have very good subversion integration if you use this IDE I recommend it, otherwise download an appropriate subversion client for your system, I will first guide you to build the program in Netbeans and then on the command line.
From the Netbeans menu choose "Team->Subversion->Checkout" and on the dialog the repository URL to enter is:
https://jpdfbookmarks.svn.sourceforge.net/svnroot/jpdfbookmarks/trunk
click next and you will get to the following another panel, choose trunk as the repository folder and check "Skip "trunk" and checkout only its content", choose the local folder, for example:
C:\Users\username\Documents\NetbeansProjects\jpdfbookmarks
and check "Scan for Netbeans Projects after Checkout", then click Finish. Wait for the download to finish and then you will get a message box, click on "Open Project ..." and on the opened dialog select the project jpdfbookmarks_core, check "Open Required" and click Open.
Run the project in Netbeans with F6 key or with the appropriate Run menu item.
If you prefer using the command line download the current source with the command:
$> svn co https://jpdfbookmarks.svn.sourceforge.net/svnroot/jpdfbookmarks/trunk jpdfbookmarks
enter the directory containing the main project with:
$> cd jpdfbookmarks/jpdfbookmarks_core
build the project with:
$> ant jar
execute the program with:
$> java -jar dist/jpdfbookmarks.jar
How to package
I have decided not to provide installers for jpdfbookmarks but only archives containing binaries, the reason is that I prefer spending my time programming and solving bugs on the code, creating installers for different platforms is not an easy task and I hope someone will offer his help to create state of the art packages for specific systems.
On Linux
Run the packager.sh script with:
$ sh packager.sh
On Windows
I suggest to use cygwin to run the packager.sh script on Windows.
How to help
There are really many ways to help a GPL project like this, here I give some hints but feel free to offer any other idea you have.
- report bugs; - correct bugs submitting patches; - write documentation or tutorials; - write translations of the program or of the documentation; - create better icons; - suggest new features; - create Installers; ...
How to Contact
If you don't feel comfortable with any of the following specialized tools use any other mean you can think of, but please give your feedback, it is the only way an open source project can grow and become a good software, thank you in advance.
How to Request Support, Report Bugs, Request Features
The best way to get support is to use the help forum otherwise you can e-mail me (you find my address in the program's about box or in the README file) or post a comment to my blog, but please try to use the forum so that your problem (and hopefully the solution) are available for anyone.
MediaWiki Default Sections
Consult the User's Guide for information on using the wiki software.
Getting started
Project Logo
Click on the following image to upload a new version of the PNG logo image for your project:
