# Pumpa v0.7.3

Greetings, fellow pumpkins!

Pumpa is a simple [pump.io][1] client written in C++ and Qt, and
licensed under the GNU GPL 3.0 (or later).

Please report any bugs or feature requests to [the bug tracker][13].
If that doesn't work for some reason, you can always contact me via
e-mail: <mats@sjoberg.fi>.

The Pumpa source code includes codes and graphics from other projects:

- The [kQOAuth library][2] is copyrighted by [Johan Paul][3] and
  licensed under LGPL 2.1.

- The current (temporary?) Pumpa logo is from the
  ["Fruit and Veggie Inventory"][4] entry to the
  [Liberated Pixel Cup][5] by Joshua Taylor.  The logo is copyrighted
  by the artist and is dual licensed under the CC-BY-SA 3.0 license
  and the GNU GPL 3.0.

- The [sundown Markdown library][8] is copyrighted by Natacha
  Port&eacute;, Vicent Marti and others, and
  [permissively licensed][9].

- [Tim Schumacher][16] contributed several improvements and installer
  code for Microsoft Windows systems.

Oh, and "pumpa" is a Swedish word that means either "to pump" (as a
verb) or "pumpkin" (as a noun) :-)


[1]: http://pump.io/
[2]: https://github.com/kypeli/kQOAuth
[3]: http://www.johanpaul.com/
[4]: http://opengameart.org/content/fruit-and-veggie-inventory
[5]: http://lpc.opengameart.org/
[8]: https://github.com/vmg/sundown
[9]: https://github.com/vmg/sundown#license
[13]: https://bugs.saz.im/pumpa

## Installing

At this point most people keep up with the git repository and compile
Pumpa themselves (for instructions how to do this, see the next two
sections).  Once Pumpa development stabilises a bit, hopefully
packages for different platforms will appear.

Below are some packages or installers for different platforms.  Note
that these are provided by third parties so I have no control over
them, please report any problems with them to the respective
packagers/authors.

### Fedora repository

[Matt Molyneaux](https://microca.st/moggers87) has created a
repository for Fedora 19:

<http://moggers.co.uk/~moggers87/repo/pumpa/>


### Microsoft Windows

[Tim Schumacher][16] has a Windows installer executable at:

<http://bandenkrieg.hacked.jp/~tim/pumpa/>

[16]: https://fmrl.me/0xAFFE

### Debian package (Spanish)

[Fabián Bonetti](https://identi.ca/mamafree) makes a Debian package
with Spanish configuration available on this page:

<http://mamalibre.no-ip.org/>


## Build dependencies
  
Pumpa should build with Qt 4.8 or Qt 5.0 or newer. If you are using Qt
4, you will also need the [QJson library][6].

For example on Debian 7.0 "wheezy" the following command should
install everything needed to build the code:

    aptitude install qt4-qmake libqt4-dev libqjson-dev

If you want spell checking install the aspell library as well:

    aptitude install libaspell-dev

On Fedora this should install what you need (courtesy of [Dick Turpin][10]):

    yum install gcc-c++ qt-devel qt-config qjson-devel

[6]: http://qjson.sourceforge.net/
[10]: https://microca.st/dick_turpin/note/toJY8CHTQlqinra0Hr6lFA

## Building

To download and build, type the following:

    git clone git://gitorious.org/pumpa/pumpa.git
    cd pumpa
    qmake-qt4     # or just "qmake" on some systems
    make

The procedure on Mac OS X is the same, but getting the dependencies is
a bit different, David Haberth&uuml;r has made a detailed guide for
building on Mac OS X here:
<https://github.com/e14n/pump.io/wiki/HowTo-for-building-Pumpa-on-OS-X>

Axel has a blog post about compiling for Windows here: <https://axel668.wordpress.com/2013/07/18/how-to-build-pumpa-qt-based-pump-io-client-for-windows/>

## Running

On Linux you can start pumpa by running its binary:

    ./pumpa

On Mac OS X a regular clickable application file (pumpa.app) should be
created.

At first launch an OAuth wizard will pop-up, just enter your pump.io
account id, and click Next. Then a the authentication page with your
pump.io server will be opened in the web browser, just follow the
instructions there. Finally a pair of codes (token, verifier) will
appear that you need to copy & paste back into pumpa.

## Markup

When you are posting a new note or comment you can use [Markdown
syntax][7], with the exception that inline HTML is **not**
allowed. This is because otherwise it would be very easy to add broken
HTML which will be very messy...

[7]: http://daringfireball.net/projects/markdown/syntax

## Configuration

Most features and configuration options should be obvious from the
graphical user interface, but some are a bit hidden.  For example,
while Pumpa doesn't support multiple accounts, you can always start it
with a different configuration file (which can specify another pump.io
account for example) like this:

    ./pumpa -c path_to_alternative.conf

If you are setting up a new account you can give the path to a
non-existent conf-file and Pumpa will run the setup wizard and create
the conf-file for you with the name you specified.

The location of the default configuration file depends on Qt, which
[tries to pick a location that makes sense for your operating system][12].
E.g. in GNU/Linux systems it is typically in:

    ~/.config/pumpa/pumpa.conf

Most configuration options are exposed via the preferences dialog in
Pumpa, except for setting the link colour.  The link colour is
supposed to be automatically set by the theme settings of your desktop
environment, but several people requested a way to override this.

You can add a line like this under the `[%General]` section in the
configuration file:

    link_color=#333

The text after the equals sign can be
[any text string that Qt can parse as a colour][11]. (Yes I know
colour is spelt wrong in the config name :-)

[11]: http://qt-project.org/doc/qt-4.8/qcolor.html#setNamedColor
[12]: http://qt-project.org/doc/qt-4.8/qsettings.html#locations-where-application-settings-are-stored


## Debug mode

If you experience crashes it may be useful to run Pumpa in debug
mode.  Right now you'll need to recompile it for that with the
following steps:

    cd pumpa
    make clean
    qmake CONFIG+=debug
    make
    
To run in the debugger (you need to have `gdb` installed):

    gdb ./pumpa

Inside gdb you then start Pumpa with the command `run`, when it has
crashed you'll be thrown back to the debugger, then type `where`,
which will tell you where it crashed. This information can be very
useful (in particular the first 10-20 lines), please include it if you
report a bug.


## Translations

Pumpa currently has a Spanish and French translation, and a German one
has been discussed. Any new translations are most welcome, but please
tell me first (<mats@sjoberg.fi>) so that people don't do duplicate
work!

If you want to translate Pumpa you need to edit a .ts file.  Any TS
translation tool is probably OK, but these instructions assume you
will use the [Linguist tool][15] that comes with Qt. Here are the
steps:

- Download and install Qt development tools, e.g. in Debian you need
  the `qt4-dev-tools` package.  You can also just install the full Qt
  system from the [Qt Project web site][14] (Linux, Mac and Windows).

- Pull the most recent version of Pumpa from git. If you have cloned
  it earlier (as described above) just do a pull to get the newest
  version:

      git pull
    
  (alternatively you could just grab the .ts file directly from the
  [gitorious web site](https://gitorious.org/pumpa/pumpa/trees/master/translations)).

- In Pumpa there should be a `translations` directory with several .ts
  files, called e.g. `pumpa_es.ts` for Spanish, `pumpa_de.ts` for
  German, and so on.  If you cannot find one for your language you can
  ask me to add it (or add it yourself, it needs a line under
  `TRANSLATIONS` in `pumpa.pro` and then run `lupdate` on the CLI).

- Open the .ts file in [Qt Linguist][15] and start filling in the
  fields in your language.  Feel free to ask any questions about the
  context of the texts, or if you want to have something improved to
  better fit your language.
  
- Some menu items and buttons have texts with ampersands,
  e.g. "&Help", this means that the next character is an
  ALT-shortcut. So in this case ALT-h would launch the Help menu.  It
  is OK to change the shortcut when translating, but make sure that
  you do not have the same shortcut for many things :-)
  
- Once you are done you can make your own clone on gitorious and make
  a pull request, or just email me the .ts file if that's easier.
  
- If you want to try it on Pumpa right away, you need to run the command:

      lrelease pumpa.pro

  (You need to use `lrelease-qt4` on some systems, e.g. Fedora.)

  Pumpa should detect your systems locale setting and use the correct
  language.  If that doesn't work, or your locale is different, you
  can always force Pumpa to pick the right one, e.g. for Spanish:

      ./pumpa -l es


[14]: https://qt-project.org/downloads
[15]: http://qt-project.org/doc/qt-4.8/linguist-translators.html

## License

Copyright 2013 Mats Sj&ouml;berg <mats@sjoberg.fi>.

All of the source code of Pumpa is licensed under the GPLv3.

*GPLv3*

Pumpa is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your
option) any later version.

Pumpa is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License
along with Pumpa.  If not, see <http://www.gnu.org/licenses/>.