Merge tag 'upstream/2.11_beta3+ds'
[debian/jabref.git] / README.md
1 # JabRef 2.11 beta 3
2
3 [![Build Status](https://api.travis-ci.org/JabRef/jabref.png?branch=master)](https://travis-ci.org/JabRef/jabref)
4 [![Dependency Status](https://www.versioneye.com/user/projects/557f2723386664002000009c/badge.svg?style=flat)](https://www.versioneye.com/user/projects/557f2723386664002000009c)
5 [![Coverage Status](https://coveralls.io/repos/JabRef/jabref/badge.svg)](https://coveralls.io/r/JabRef/jabref)
6 [![Join the chat at https://gitter.im/JabRef/jabref](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/JabRef/jabref?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
7
8 This version is a beta version. Features may not work as expected.
9
10 JabRef is a graphical Java application for editing bibtex (`.bib`) databases.
11 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.
12 You can customize the entry information shown in the main window, and sort by any of the standard Bibtex fields.
13 JabRef can autogenerate bibtex keys for your entries.
14 JabRef also lets you easily link to PDF or web sources for your reference entries.
15
16 JabRef can import from and export to several formats, and you can customize export filters.
17 JabRef can be run as a command line application to convert from any import format to any export format.
18
19 * Homepage: http://jabref.sourceforge.net/
20 * Development mailinglist: https://lists.sourceforge.net/lists/listinfo/jabref-devel
21 * Development page: https://github.com/JabRef
22 * Main git repository: https://github.com/JabRef/jabref
23 * CI Server: https://travis-ci.org/JabRef/jabref
24 * Open HUB page: https://www.openhub.net/p/jabref
25
26 The main git repository has been generated out of the old git repository at sourceforge.
27 The folder `jabref` of the old repository is now the main repository.
28 Although that changed **all** git commit ids, the advantage is to have a clean separation between plugins, the homepage and the code of JabRef.
29
30
31 ### Bug reports, suggestions, other feedback
32
33 We are thankful for any bug reports or other feedback. If there are
34 features you want included in JabRef, tell us!
35
36 The "old" trackers at sourceforge still remain intact:
37
38 * Bugs: https://sourceforge.net/p/jabref/bugs/
39 * Feature Requests: https://sourceforge.net/p/jabref/feature-requests/
40
41 Do *not* file patches using https://sourceforge.net/p/jabref/patches/.
42 Just fork JabRef and create a pull request.
43 For details see [CONTRIBUTING.md](CONTRIBUTING.md).
44
45 ### Next Steps
46
47 * Completely change build system from `ant` to `gradle` to get rid of the binaries in the repository.
48 * Migrate the sourceforge wiki to github
49 * Fix bugs listed at https://sourceforge.net/p/jabref/bugs/.
50
51
52 ## Requirements
53
54 JabRef runs on any system equipped with the Java Virtual Machine (1.6 or newer), which can be downloaded at no cost from [Oracle](http://www.oracle.com/technetwork/java/javase/downloads/index.html).
55 If you do not plan to compile JabRef, the Java Runtime Environment may be a better choice than the Java Development Kit.
56
57
58 ## Installing and running, Mac OS X:
59
60 Please see our [Mac OS X FAQ](http://jabref.sourceforge.net/faq.php#osx).
61
62
63 ## Installing and running, Windows:
64
65 JabRef offers an installer, which also adds a shortcut to JabRef to your start menu.
66
67 Please also see our [Windows FAQ](http://jabref.sourceforge.net/faq.php#windows)
68
69
70 ## Installing and running, general:
71
72 JabRef can be downloaded as an executable .jar file.
73 Try to doubleclick the `jar` file or execute the follwing command:
74      `java -jar <path to jar>`
75
76 If you run JabRef under Java 1.5, you can add the option `-Dswing.aatext=true` before the
77 `-jar` option, to activate antialiased text throughout the application.
78
79
80 ## Documentation
81
82 JabRef comes with an online help function, accessed by pressing F1 or
83 clicking on a question mark icon. The help files are probably not
84 exhaustive enough to satisfy everyone yet, but they should help sort
85 out the most important issues about using the program. The help files
86 can also be viewed outside the program with a standard HTML browser.
87 If you choose languages other than English, some or all help pages may
88 appear in your chosen languages.
89
90
91 ## Building JabRef from source:
92
93 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)
94
95 To compile JabRef from source, you need a Java compiler supporting Java 1.6 and `JAVA_HOME` pointing to this JDK.
96
97 To run it, just execute `gradlew run`.
98 When you want to develop, it is necessary to generate additional sources using `gradlew generateSource`
99 and then generate the Eclipse `gradlew eclipse` or IntelliJ IDEA `gradlew idea` project files.
100
101
102 ## Release Process
103
104 Requires
105  * [launch4j](http://launch4j.sourceforge.net/)
106  * [NSIS](http://nsis.sourceforge.net) with the [WinShell plug-in](http://nsis.sourceforge.net/WinShell_plug-in).
107  * Eventually a `user.properties` with correct setting of `launch4j.dir` and `nsis.executable`. See [build.xml](build.xml) for defaults.
108
109 Replace `ANY_ANT_TARGET` with the Ant Target of your choice (e.g., `macbundle`), and the system will build your binaries.
110 To get a list of all targets, use `gradlew tasks`.
111
112 `gradlew generateSource antTargets.ANY_ANT_TARGET`
113
114 To compile, use the command `gradlew generateSource antTargets.jars`.
115 After the build is finished, you can find the executable jar file
116 named `JabRef-$VERSION.jar` (where $VERSION is the current version of the
117 source tree) in the `buildant\lib` directory. Enjoy!
118 The setup files are created by invoking the command `gradlew generateSource antTargets.release`.
119
120
121 ### Releasing on Linux
122
123 Run `gradlew antTargets.release.linux`
124
125 All binaries (including OSX) and the installer are generated in the directory `buildant/lib`.
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 2 of the License, or (at your option) any later
140 version.
141 See the enclosed text files [gpl2.txt](gpl2.txt) and [gpl3.txt](gpl3.txt) for full details.
142
143 JabRef also uses libraries distributed by other parties; see the About box for details.