Agordejo/documentation/english.adoc

:Author: Laborejo Software Suite
:Version: 0.1
:iconfont-remote!:
:!webfonts:


////
This documentation is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.
To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ or send a
letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
A copy of the license has been provided in the file documentation/LICENSE.
////

////
https://powerman.name/doc/asciidoc
https://asciidoctor.org/docs/user-manual/
////

:sectnums:

:toc: left
:toc-title: Table of Contents
:toclevels: 3

= Argodejo

// Don't write in the empty line above line. It will be interpreted as author html tag
For program version 0.1

== Introduction


Argodejo (Esperanto: 'place to set things up') is a music production session manager.
It is used to start your programs, remember their (JACK) interconnections and make your life easier
in general.


You can seamlessly change between two view modes to quickly start a few programs or have complete
control and a detailed overview.


Argodejo does not re-invent the wheel but instead uses the New-Session-Manager daemon and enhances
it with some tricks of its own, that always remain 100% compatible with the original sessions.


This is a proof of concept version. It aims to show that session management with NSM can be quick
and convenient and make the user feel in control. Some functionality has not yet been
implemented, most prominently anything related to NSM over network. There is always the possibility to
break things when trying out corner cases and hacks.


That said, for single-computer sessions with just one daemon and one GUI at the same time Argodejo
should provide a good user experience.


<manual>

== Installation and Start

Argodejo is exclusive for Linux. The best way to install is to use your package manager. 
If it is not there, or only in an outdated version, please ask your Linux distribution to provide a recent version.

If available in the package repository, please continue reading directly at "Start argodejo from Non Session Manager".
If not, you can build Argodejo yourself.

.Build and Install
* Please check the supplied README.md for dependencies.
* You can download a release or clone the git version
  ** Download the latest version from https://www.laborejo.org/downloads and extract it.  
  ** git clone https://git.laborejo.org/lss/argodejo.git
* Change into the new directory and use these commands:
* `./configure --prefix=/usr`
  ** The default prefix is /usr/local
* `make`
* `sudo make install`

.Start argodejo from Non Session Manager (NSM)
* Run `non-session-manager`
* Press the `New` button, and enter a name for your piece of music.
* Press the `Add Client to Session` button, enter `argodejo` here, in lower case.
* Add Client again, this time `jackpatch`.
* Add any compatible programs, e.g. synthesizers.
** See the list of NSM compatible programs: http://non.tuxfamily.org/wiki/ApplicationsSupportingNsm
** And the NSM manual: http://non.tuxfamily.org/nsm/

Please read README.md for other ways of starting argodejo, which are impractical for actual use but can
be helpful for testing and development.

== Help and Development
You can help Argodejo in several ways: Testing and reporting errors, translating, marketing, support, programming and more.

=== Testing and Reporting Errors
If you find a bug in the program (or it runs too slow) please contact us in a way that suits you best.
We are thankful for any help.

.How to contact us
* Report bugs and issues: https://www.laborejo.org/bugs
* Website: https://www.laborejo.org
* E-Mail: info@laborejo.org
* If you see the opportunity and know that a developer will read it also forums, social media etc..

=== Programming
If you want to do some programming and don't know where to start please get in contact with us directly.
The short version is: clone the git, change the code, create a git patch or point me to your public git.

=== Translations
Argodejo is very easy to translate with the help of the Qt-Toolchain, without any need for programming.
The easiest way is to contact the developers and they will setup the new language.

However, here are the complete instructions for doing a translation completely on your own and integrating it into the program.
The program is split in two parts. A shared "template" between the Laborejo Software Suite and the actual program.

The process is the same for both parts, but needs to be done in different directories:
`template/qtgui` and plain `/qtgui`, relative to the root directory, where the argodejo executable is.

Everytime you see "template/qtgui" below you can substitute that with just "qtgui" to translate the other part of Argodejo.

You can add a new language like this: 

* Open a terminal and navigate to template/qtgui/resources/translations
* Edit the file `config.pro` with a text editor
  ** Append the name of your language in the last line, in the form `XY.ts`, where XY is the language code.
  ** Make sure to leave a space between the individual languages entries.
* Run `sh update.sh` in the same directory
  ** The program has now generated a new `.ts` file in the same directory.
* Start Qt Linguist with `linguist-qt5` (may be named differently) and open your newly generated file
* Select your "Target Language" and use the program to create a translation
* Send us the `.ts` file, such as by e-mail to info@laborejo.org

You can also incorporate the translation into Argodejo for testing purposes. This requires rudimentary Python knowledge.

* Run the "Release" option in QtLinguists "File" menu. It creates a `.qm` file in the same directory as your `.ts` file.
* Edit `template/qtgui/resources/resources.qrc` and duplicate the line `<file>translations/de.qm</file>` but change it to your new .qm file.
* run `sh buildresources.sh`
* Edit `engine/config.py`: add your language to the line that begins with "supportedLanguages" like this: `{"German": "de.qm", "Esperanto: "eo.qm"}`
  ** To find out your language string (German, Esperanto etc.) open the `python3` interpreter in a terminal and run the following command:
  ** `from PyQt5 import QtCore;QtCore.QLocale().languageToString(QtCore.QLocale().language())`

To test the new translation you can either run the program normally, if your system is set to that language. Alternatively start argodejo via the terminal:

* `LANGUAGE=de_DE.UTF-8 ./argodejo -V --save /dev/null`