-
Notifications
You must be signed in to change notification settings - Fork 2
/
README
316 lines (239 loc) · 12.7 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
===============================================================================
This is jpdfbookmarks
Copyright (c) 2008 2009 2010 Flaviano Petrocchi <[email protected]>
except where differently indicated in source code.
License: GNU General Public License version 3
Author's Blog: http://flavianopetrocchi.blogspot.com/
source-forge: http://sourceforge.net/projects/jpdfbookmarks/
For licence information read COPYING file, read the dependencies section in
this README for the licenses and copyright of the open source libraries used
by this project.
===============================================================================
Sections:
- DESCRIPTION
- NOTES FOR THIS BRANCH
- DEPENDENCIES
- HOW TO INSTALL AND UNINSTALL
- HOW TO EXECUTE
- HOW TO BUILD
- HOW TO PACKAGE
- HOW TO HELP
*******************************************************************************
DESCRIPTION
*******************************************************************************
This software allows you to create and edit bookmarks on existing pdf files.
*******************************************************************************
NOTES FOR THIS BRANCH
*******************************************************************************
This branch provides a version which builds with the current (as of
July 1, 2020) version of NetBeans, NetBeans 12.0. It also provides
macOS support, using the macOS menu bar and the macOS CMD key (Java
meta key) for crucial keyboard accelerators.
*******************************************************************************
DEPENDENCIES
*******************************************************************************
This software requires a Java Runtime Environment version 9 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. It uses the following libraries distributed in the lib folder
which are copyright of their respective authors:
Apache Commons CLI
Copyright 2001-2009 The Apache Software Foundation
http://commons.apache.org/cli/
Apache License Version 2.0, January 2004
http://www.apache.org/licenses/
iText-2.1.7
Copyright 1999, 2000, 2001, 2002 by Bruno Lowagie.
http://www.lowagie.com/iText/
GNU LIBRARY GENERAL PUBLIC LICENSE Version 2 (or later version)
http://www.gnu.org/licenses/
Bouncy Castle Crypto APIs
Copyright (c) 2000 - 2009 The Legion Of The Bouncy Castle
http://www.bouncycastle.org
Adaptation of the MIT X11 License
http://www.bouncycastle.org/licence.html
JPedal
(C) Copyright 1997-2008, IDRsolutions and Contributors.
http://www.jpedal.org
GNU Lesser General Public License Version 2.1 (or later version)
http://www.gnu.org/licenses/
Icons are from the "Tango Desktop Project"
http://tango.freedesktop.org/Tango_Desktop_Project
*******************************************************************************
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 like /usr/local/bin for
example with the root commands:
# cd /usr/local/bin
# 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 jpdfbookmars
or to create a launcher icon in any desktop easily.
The only difference between the *_cli (command-line-interface) version and the
other script is that the cli version does not use a splash screen so it's more
tailored to be used inside a terminal, choose what you prefer to link.
To uninstall on linux just delete the extracted folder and delete the link in
the PATH folder if you created it with the command:
$rm /usr/local/bin/jpdfbookmarks
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 [--dump | --apply <bookmarks.txt> --out <output.pdf> |
--help | --version] [input.pdf]
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.
-d,--dump Extract bookmarks from a PDF file passed as
argument and print them to standard output.
-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> Output PDF file --out file.pdf or -o file.pdf. Use
with the --apply option.
-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.
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
*******************************************************************************
HOW TO BUILD
*******************************************************************************
My development environment is the JDK 6, I use the Netbeans IDE version 6.7.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.
To create the archives there are two scripts in the Packaging folder,
packager.bat if you are in Windows, and packager.sh if you are on Linux.
On Windows
==========
The packager.bat batch script depends on 7zip software to create the archives,
you must modify the script to use it on your system, find the line:
SET PATH7ZIP="D:\LiberKey\Apps\7Zip\App\7-Zip"
and substitute the path with the 7zip installation folder on your system, than
simply run the batch file after you have built jpdfbookmarks to create the
zip and tar.gz archives.
On Linux
========
Run the packager.sh script with:
$ sh packager.sh
*******************************************************************************
HOW TO HELP
*******************************************************************************
There are really many ways to help a small 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;
...
For more instructions and information go to my blog
http://flavianopetrocchi.blogspot.com/ or to
http://sourceforge.net/projects/jpdfbookmarks/ please post your comments and bug
reports.
I hope this will help you getting your job done, let me know.
Best Regards,
Flaviano Petrocchi