update some paths again
[debian/jabref.git] / README.md
1 # JabRef version 2.11 beta 2
2
3 This version is a beta version. Features may not work as expected.
4
5 JabRef is a graphical Java application for editing bibtex (`.bib`) databases.
6 JabRef lets you organize your entries into overlapping logical groups, and with a single click limit your view to a single group or an intersection or union of several groups.
7 You can customize the entry information shown in the main window, and sort by any of the standard Bibtex fields.
8 JabRef can autogenerate bibtex keys for your entries.
9 JabRef also lets you easily link to PDF or web sources for your reference entries.
10
11 JabRef can import from and export to several formats, and you can customize export filters.
12 JabRef can be run as a command line application to convert from any import format to any export format.
13
14 * Homepage: http://jabref.sourceforge.net/
15 * Development page: https://github.com/JabRef
16 * Main git repository: https://github.com/JabRef/jabref
17 * CI Server: https://travis-ci.org/JabRef/jabref
18 * Open HUB page: https://www.openhub.net/p/jabref
19
20 The main git repository has been generated out of the old git repository at sourceforge.
21 The folder `jabref` of the old repository is now the main repository.
22 Although that changed **all** git commit ids, the advantage is to have a clean separation between plugins, the homepage and the code of JabRef.
23
24
25 ### Bug reports, suggestions, other feedback
26
27 We are thankful for any bug reports or other feedback. If there are
28 features you want included in JabRef, tell us!
29
30 The "old" trackers at sourceforge still remain intact:
31
32 * Bugs: https://sourceforge.net/p/jabref/bugs/
33 * Feature Requests: https://sourceforge.net/p/jabref/feature-requests/
34
35 Do *not* file patches using https://sourceforge.net/p/jabref/patches/.
36 Just fork JabRef and create a pull request.
37
38 For newcomers, [FLOSS Coach](http://www.flosscoach.com/) might be helpful. It contains steps to get start with JabRef development.
39
40
41 ### Next Steps
42
43 * Completely change build system from `ant` to `gradle` to get rid of the binaries in the repository.
44 * Migrate the sourceforge wiki to github
45 * Fix bugs listed at https://sourceforge.net/p/jabref/bugs/.
46
47
48 ## Requirements
49
50 JabRef runs on any system equipped with the Java Virtual Machine (1.6 or newer), which can be downloaded at no cost from http://java.sun.com.
51 If you do not plan to compile JabRef, the Java Runtime Environment may be a better choice than the Java Development Kit.
52
53
54 ## Installing and running, Windows:
55
56 JabRef is available in Windows Installer (`.msi`) format. To install,
57 double-click the .msi file. A shortcut to JabRef will be added to your
58 start menu.
59
60 The Windows installation was made by Dale Visser, using the following open-source tools:
61 JSmooth (.exe wrapper for Java apps), available at http://jsmooth.sf.net/
62 Wix (tool for compiling MSI files from an XML specification), available at http://wix.sf.net/
63
64
65 ## Installing and running, general:
66
67 JabRef can be downloaded as an executable .jar file. Run the
68 program as follows:
69 If you are using the Java Development Kit:
70      `java -jar <path to jar>`
71 or, if you are using the Java Runtime Environment:
72      `jre -new -jar <path to jar>` or
73      `jrew -new -jar <path to jar>`
74
75 If you run JabRef under Java 1.5, you can add the option `-Dswing.aatext=true` before the
76 `-jar` option, to activate antialiased text throughout the application.
77
78 The jar file containing JabRef can be unpacked with the command:
79     `jar xf <path to jar>`
80 or  `jar xf <path to jar> <list of files to extract>`.
81 Unpacking the jar file is not necessary to run the program.
82
83
84 ## Documentation
85
86 JabRef comes with an online help function, accessed by pressing F1 or
87 clicking on a question mark icon. The help files are probably not
88 exhaustive enough to satisfy everyone yet, but they should help sort
89 out the most important issues about using the program. The help files
90 can also be viewed outside the program with a standard HTML browser.
91 If you choose languages other than English, some or all help pages may
92 appear in your chosen languages.
93
94
95 ## Building JabRef from source:
96
97 If you want a step-by-step tutorial, please check [this guideline](https://github.com/JabRef/jabref/wiki/Guidelines-for-setting-up-a-local-workspace)
98
99 To compile JabRef from source, you need a Java compiler supporting Java 1.6 and `JAVA_HOME` pointing to this JDK.
100
101 To run it, just execute `gradlew run`.
102 When you want to develop, it is necessary to generate additional sources using `gradlew generateSource`
103 and then generate the Eclipse `gradlew eclipse` or IntelliJ IDEA `gradlew idea` project files.
104
105
106 ## Release Process
107
108 Requires
109  * [launch4j](http://launch4j.sourceforge.net/)
110  * [NSIS](http://nsis.sourceforge.net) with the [WinShell plug-in](http://nsis.sourceforge.net/WinShell_plug-in).
111
112 Replace `ANY_ANT_TARGET` with the Ant Target of your choice, and the system will build your binaries.
113 To get a list of all targets, use `gradlew tasks`.
114
115 `gradlew generateSource antTargets.ANY_ANT_TARGET`
116
117 To compile, use the command `gradlew generateSource antTargets.jars`.
118 After the build is finished, you can find the executable jar file
119 named `JabRef-$VERSION.jar` (where $VERSION is the current version of the
120 source tree) in the `buildant\lib` directory. Enjoy!
121 The setup files are created by invoking the command `gradlew generateSource antTargets.release`.
122
123 On Mac OS X you should include the targets osx and osxjar,
124 making the correct command `gradlew generateSource antTargets.compile antTargets.unjarlib antTargets.osx antTargets.jars antTargets.osxjar`.
125 After the build is finished, you will find the OS X application
126 `JabRef.app` in the `buildant/lib` directory along with the executable
127 jar.
128
129
130 ### Releasing on Windows
131
132 Run `gradlew antTargets.release`
133
134 All binaries (including OSX) and the installer are generated in the directory `buildant/lib`.
135
136
137 ## License
138
139 JabRef is free software: you can redistribute it and/or modify it under the
140 terms of the GNU General Public License as published by the Free Software
141 Foundation, either version 3 of the License, or (at your option) any later
142 version.
143 See the enclosed text files 'gpl3.txt' for full details.
144
145 JabRef also uses libraries distributed by other parties; see the About box for details.