New upstream release.
[debian/jabref.git] / README.md
1 # JabRef version 2.11 beta
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 [NSIS](http://nsis.sourceforge.net) with the [WinShell plug-in](http://nsis.sourceforge.net/WinShell_plug-in).
109
110 Replace `ANY_ANT_TARGET` with the Ant Target of your choice, and the system will build your binaries.
111 To get a list of all targets, use `gradlew tasks`.
112
113 `gradlew generateSource antTargets.ANY_ANT_TARGET`
114
115 To compile, use the command `gradlew generateSource antTargets.jars`.
116 After the build is finished, you can find the executable jar file
117 named `JabRef-$VERSION.jar` (where $VERSION is the current version of the
118 source tree) in the `buildant\lib` directory. Enjoy!
119 The setup files are created by invoking the command `gradlew generateSource antTargets.release`.
120
121 On Mac OS X you should include the targets osx and osxjar,
122 making the correct command `gradlew generateSource antTargets.compile antTargets.unjarlib antTargets.osx antTargets.jars antTargets.osxjar`.
123 After the build is finished, you will find the OS X application
124 `JabRef.app` in the `buildant/lib` directory along with the executable
125 jar.
126
127
128 ### Releasing on Windows
129
130 Run `gradlew antTargets.release`
131
132 All binaries (including OSX) and the installer are generated in the directory `buildant/lib`.
133
134
135 ## License
136
137 JabRef is free software: you can redistribute it and/or modify it under the
138 terms of the GNU General Public License as published by the Free Software
139 Foundation, either version 3 of the License, or (at your option) any later
140 version.
141 See the enclosed text files 'gpl3.txt' for full details.
142
143 JabRef also uses libraries distributed by other parties; see the About box for details.