# Manuel de &karm;

## Introduction

&karm; comptabilise le temps passé sur diverses tâches. Il est employé pour connaître les heures à facturer et peut vous renseigner sur le temps passé par tâche et par jour.

Un historique peut être exporté dans un fichier CSV afin de l'employer dans un logiciel de facturation ou de gestion de projets.

&karm; détecte l'inactivité de vos clavier et souris et peut associer différentes tâches à différents bureaux, deux outils qui vous aident à chronométrer correctement vos travaux.

À l'origine &karm; a été écrit par Sirtaj Singh Kang. Dans la langue de l'auteur, le Punjabi, le mot karm signifie travail ou actions. C'est également le même mot (dans une meilleure transcription) que karma.

## Utiliser &karm;

### Démarrer &karm;

Saisissez `karm` en ligne de commande ou choisissez Chronomètre individuel de tâches du groupe Utilitaires dans le menu K. Les commandes standard de &Qt; et &kde; sont disponibles et peuvent être listées en saisissant ``karm` `--help`` en ligne de commande.

&karm; fournit une option supplémentaire qui vous permet de saisir le nom d'un fichier iCalendar qui sera utilisé pour stocker l'historique de votre travail. Pour spécifier l'emplacement d'un fichier iCalendar distant vous utiliserez HTTP ou FTP dans le nom du fichier : par exemple, http://www.monsite.com/mesdonnees/montravail.ics.

### Tâches

Problème : vous êtes un consultant en logiciels libres avec de nombreux clients. Certains d'entre eux ont plusieurs projets. Tout au long de la journée, vous passez d'un projet à l'autre. Vous avez besoin de comptabiliser le temps passé sur chacun pour facturer vos clients.

Solution : créez une tâche principale pour chaque client et une sous-tâche pour chaque projet. Pour les projets qui requièrent plus de détails, créez d'autre sous-tâches. Pour chronométrer les tâches sur lesquelles vous travaillez, il vous suffit de double-cliquer sur celles-ci.

&karm; fait preuve d'une grande flexibilité dans le suivi des durées, ce qui lui permet de gérer un nombre illimité de tâches et sous-tâches. Les durées sont comptabilisées pour n'importe lesquelles et plusieurs peuvent être actives en même temps.

Pour créer une tâche principale, faites &Ctrl;N Tâche Nouvelle Pour créer une sous-tâches, choisissez une tâche principale et faites &Ctrl;&Alt;N Tâches Nouvelle sous-tâche

À la fermeture de &karm;, la liste des tâches est enregistrée dans le fichier spécifié dans Configuration Configurer &karm; . Au lancement suivant, elle sera rechargée à partir de ce fichier.

Pour vous faciliter la vie, &karm; peut importer et exporter des tâches. Voir Autres systèmes.

### Compteurs

Problème : pour rester solvable, vous devez facturer une moyenne de cinq heures par jour. Vous vous en assurez en regardant vos totaux journalier et hebdomadaire.

Solution : réinitialisez le chronomètre de la session au début de chaque journée de travail et réinitialisez tous les compteurs au début de chaque semaine.

&karm; permet de chronométrer simplement. Pour commencer à comptabiliser la durée d'une tâche, double-cliquez sur celle-ci. Pour arrêter la comptabilisation, double-cliquez à nouveau. Les tâches actives affichent un petit chronomètre dans la colonne Durée de la session.

Un autre indice visuel de cette comptabilisation est la miniature de &karm;. Lorsqu'une tâche est active, le (tout) petit chronomètre bouge. Si vous passez votre souris au-dessus de cette icône, le nom de cette tâche s'affichera dans une bulle d'aide. Si plusieurs sont en cours, leurs noms seront séparés par des virgules.

&karm; maintient deux compteurs pour chaque tâche : un pour la durée de la session et l'autre pour la durée totale. Par défaut, &karm; affiche deux colonnes pour chaque compteur, ce qui donne quatre colonnes pour chaque tâche :

Durée de la session

- Le temps passé sur la tâche depuis le début de la session.

Durée totale de la session

- Le temps passé sur la tâche et toutes ses sous-tâches depuis le début de la session.

Durée

- Le temps passé sur la tâche depuis la réinitialisation de tous les compteurs.

Durée totale

- Le temps passé sur la tâche et toutes ses sous-tâches depuis la réinitialisation de tous les compteurs.

Pour commencer une nouvelle session, faites Fichier Démarrer une nouvelle session

Pour réinitialiser toutes les durées, faites Fichier Réinitialiser toutes les durées

#### Suivi de bureaux

Problème : vous avez deux projets principaux et vous passez d'un à l'autre au cours de la journée. Pour faciliter l'organisation de votre travail, vous avez les fichiers de votre projet 1 sur le Bureau 1 et ceux de votre projet 2 sur le Bureau 2.

Solution : associez la tâche du projet 1 au Bureau 1 et celle du projet 2 au Bureau 2. Lorsque vous passerez d'un bureau à l'autre, &karm; stoppera automatiquement le projet sur lequel vous étiez et commencera l'autre.

Pour associer une tâche à un ou plusieurs bureaux, faites &Ctrl;E Tâche Modifier . Activez Suivi automatique et sélectionnez le ou les bureaux à associer. Lorsqu'un de ces bureaux deviendra actif, &karm; déclenchera automatiquement (après un court délai) le chronomètre correspondant à la tâche.

#### Détection des moments de pause

Problème : vous quittez votre travail un peu plus tôt le vendredi pour faire une course et vous oubliez d'arrêter le chronomètre. À votre retour le lundi, le compteur continue de tourner.

Solution : activez la détection d'inactivité.

&karm; peut être configuré pour détecter l'inactivité de vos clavier et souris. Si cela ce produit pour une durée plus longue que celle définie, &karm; affiche la boîte de dialogue suivante :

Détection des moments de pause par &karm; Boîte de dialogue "Détection des moments de pause" de &karm;

Revenir en arrière et arrêter

- Soustrait la durée d'inactivité à tous les compteurs actifs et les stoppent.

  Vous ne travailliez pas sur la/les tâche(s) pendant que l'ordinateur était inactif et ce n'est toujours pas le cas.

Revenir en arrière et continuer

- Soustrait la durée d'inactivité à tous les compteurs actifs tout en les laissant actifs.

  Vous ne travailliez pas sur la/les tâche(s) pendant que l'ordinateur était inactif mais vous reprenez là où vous vous êtes arrêté.

Continuer à chronométrer

- Ajoute la durée d'inactivité à tous les compteurs actifs tout en les laissant actifs.

  Vous travailliez sur la/les tâche(s) pendant que l'ordinateur était inactif et c'est toujours le cas.

### Rapport

&karm; fournit trois manières de rapporter les durées que vous avez enregistrées. Vous pouvez envoyer à une imprimante les totaux globaux et de sessions, copier les totaux de durées dans le presse-papiers ou copier l'historique des durées dans le presse-papiers.

#### Imprimer les totaux

Pour imprimer un rapport sur les totaux, faites &Ctrl;P Fichier Imprimer . Ceci génère un compte rendu sur trois colonnes pour la liste complète des tâches. La première colonne contient le nom de la tâche, la seconde colonne contient la Durée totale de la session et la troisième colonne, la Durée Totale.

#### Totaux pour le presse-papiers

Pour envoyer le rapport des totaux dans le presse-papiers, faites &Ctrl;C Fichier Copier les totaux dans le presse-papiers .

Le rapport est généré pour la tâche actuellement sélectionnée ainsi que pour toutes ses sous-tâches. S'il s'agit d'une tâche principale, &karm; demandera si vous souhaitez obtenir un compte rendu pour la tâche actuelle et ses sous-tâches ou pour toute les tâches de la liste.

&karm; copie cette tâche Boîte de dialogue "Copier cette tâche" de &karm;

Une fois le rapport créé, ouvrez Kate ou n'importe quel autre éditeur de texte et collez les données.

    Totaux de la tâche
    10/07/2007 02:26

      Durée    Tâche
    ----------------------------------------------
      9:14    kde
       9:14    karm
        1:08    bogues
        0:00    vérifier les changements
       0:00    promo
       0:00    web
    ----------------------------------------------
      9:14 Total

La première colonne contient la Durée totale et elle est indentée (tout comme les noms) pour indiquer les relations entre les tâches et sous-tâches. Les durées indiquées incluent celles des sous-tâches.

#### Historique pour le presse-papiers

Pour envoyer l'historique des totaux dans le presse-papiers, faites &Ctrl;&Alt;C Fichier Copier l'historique dans le presse-papiers .

Vous devez activer l'option Historique dans Configuration Configurer &karm; . Autrement, &karm; ne comptabilise que les totaux et pas l'historique détaillé des tâches.

Le rapport est crée pour la tâche actuellement sélectionnée et toutes ses sous-tâches. Contrairement au rapport sur les totaux, celui-ci ne vous donne pas la possibilité d'avoir la liste complète des tâches. Vous pouvez seulement faire un rapport sur la tâche actuelle et ses sous-tâches.

La première chose que &karm; vous demande est de saisir une gamme de dates :

Saisissez une gamme de dates pour &karm; Saisissez une gamme de dates pour &karm;

Après avoir saisi ces dates, ouvrez Kate ou un autre éditeur de texte et collez les données.

    Historique de la tâche
    Du jeudi 1 juillet 2004 au lundi 12 juillet 2004
    Imprimé le : 12/07/2004 17:18

                                   Semaine du lundi 5 juillet 2004
         5     6     7     8     9    10    11
    -------------------------------------------------------------------------
                                                 0:00 kde
                                                 0:00  dc
                  1:22  1:46  3:14  1:44         8:06  karm
                                                 0:00   3.2 fonctionnalités
                  1:08                           1:08   bogues
                                                 0:00   vérifier les changements
                                                 0:00  promo
                                                 0:00  web
    -------------------------------------------------------------------------
                  2:30  1:46  3:14  1:44         9:14 Total

L'historique, groupé par semaine, inclut le total pour chaque jour et tâche. Les sept premières colonnes vont du lundi au dimanche. La huitième contient le total pour la semaine et la neuvième colonne, le nom de la tâche. Les noms sont indentés pour indiquer les relations entre les tâches et sous-tâches.

### Autres systèmes

#### KOrganizer

&karm;, comme KOrganizer et iCal d'Apple, utilise le format industriel standard iCalendar pour ses données. &karm; peut lire et écrire les listes générées par ces deux applications.

Si &karm; et KOrganizer ont tous les deux le même fichier ouvert et que vous le modifiez avec KOrganizer, vous risquez de perdre des données. Par précaution, il vaut mieux modifier le fichier avec un seul de ces programmes.

#### Planner

Une utilisation typique serait de planifier un projet avec l'outil de gestion de projets Planner et d'importer ses tâches dans &karm; pour les avoir au format industriel standard iCalendar. Après cela, vous pourrez programmer les tâches dans KOrganizer et compté le temps passé sur celle-ci avec &karm;. C'est une manière de s'assurer que votre projet sera dans les temps et ne dépassera pas le budget.

#### &DCOP;

&DCOP; est un mécanisme utilisé par les programmes KDE pour communiquer entre eux. Un programme KDE fournit une liste de fonctions que les autres programmes (un script Bash, par exemple) peuvent utiliser.

##### Un script Bash donnant la version de &karm;

    DCOPID=`dcop | grep karm`
            if [ $DCOPID ]
            then
                    VERS=`dcop $DCOPID KarmDCOPIface version`
                    echo "&karm; version is $VERS"
            else
                    echo "&karm; not running"
            fi

L'interface &DCOP; de &karm; et actuellement utilisée principalement pour automatiser des tests, ce qui la rend plutôt limitée. Pour une définition complète de l'interface voyez l'annexe Interface &DCOP;.

Pour voir l'interface &DCOP; complète de la version de &karm; installée sur votre système, lancez le script Bash suivant :

##### Liste l'interface &DCOP; de &karm; dans la console

    DCOPID=`dcop | grep karm`
            if [ $DCOPID ]
            then
                    dcop $DCOPID KarmDCOPIface
            else
                    echo "&karm; n'est pas lancé"
            fi

#### Exporter les totaux dans un fichier CSV

&karm; peut exporter les totaux et l'historique dans un format de fichier dont les données sont séparées par des virgules. Pour exporter les totaux, faites Fichier Importer / exporter Exporter dans un fichier CSV... et &karm; affiche la boîte de dialogue d'exportation suivante :

Boîte de dialogue "Exporter dans un fichier CSV" de &karm; Boîte de dialogue "Exporter dans un fichier CSV" de &karm;

Saisissez le fichier vers lequel vous souhaitez exporter les données, et modifiez les autres options si nécessaire. Notez que la gamme de dates n'est pas disponible puisque vous exportez les totaux de durées, pas l'historique. Cliquez sur Exporter afin que &karm; exporte les totaux de toutes les tâches.

Voici un exemple de sortie de ce format :

    "kde",,,,,0.00,0.00,6.88,9.83
    ,"karm",,,,6.88,8.70,6.88,9.83
    ,,"3.2 fonctionnalités",,,0.00,0.00,0.00,0.00
    ,,"bogues",,,0.00,1.13,0.00,1.13
    ,,"vérifier les changements - chaînes de traduction",,,0.00,0.00,0.00,0.00
    ,,"feuille de présence",,,0.00,0.00,0.00,0.00
    ,"kopete",,,,0.00,0.00,0.00,0.00
    ,"promo",,,,0.00,0.00,0.00,0.00
    ,"web",,,,0.00,0.00,0.00,0.00

Les tâches principales se trouvent dans la première colonne, les sous-tâches dans la seconde et ainsi de suite. Les durées s'affichent après la profondeur maximale de tâches (cinq dans cet exemple). La première colonne de temps contient la Durée de la session, la seconde : la Durée, la troisième : la Durée totale de la session et la quatrième : la Durée totale.

#### Exporter l'historique dans un fichier CSV

Pour exporter l'historique de la tâche, faites Fichier Importer / exporter Exporter l'historique dans un fichier CSV... et &karm; affiche la même boîte de dialogue d'exportation que ci-dessus.

Saisissez le fichier vers lequel vous souhaitez exporter les données, et sélectionnez une gamme de dates pour l'historique. Modifiez les autres options si nécessaire. Cliquez sur Exporter pour que &karm; exporte l'historique de toutes les tâches vers le fichier que vous avez sélectionné.

Voici un exemple de sortie de ce format :

    Historique de la tâche
    Du mardi 06 juillet 2004 au mardi 13 juillet 2004
    Imprimé le : 13/07/2004 18:10
    2004-07-06,2004-07-07,2004-07-08,2004-07-09,2004-07-10,2004-07-11,2004-07-12,2004-07-13,
    ,,,,,,,,0.00,"kde"
    ,,1.77,3.23,1.73,,1.37,0.82,8.95,,"karm"
    ,,,,,,,,0.00,,,"3.2 fonctionnalités"
    ,1.13,,,,,,,1.13,,,"bogues"
    ,,,,,,,,0.00,,,"vérifier les changements - chaînes de traduction"
    ,,,,,,,,0.00,,,"feuille de présence"
    ,,,,,,,,0.00,,"kopete"
    ,,,,,,,,0.00,,"promo"
    ,,,,,,,,0.00,,"web"

Les trois premières lignes indiquent quand le rapport a été généré et pour quelle intervalle. La quatrième ligne contient une liste de dates de la gamme séparé par des virgules, au format ISO 8601 (AAAA-MM-JJ). Les autres lignes listent les durées de chaque tâche. La dernière colonne des nombres représente le total de tous les jours. Le nom de la tâche s'affiche après le total et le nombre de colonnes indique les relations entre les tâches et sous-tâches. Les tâches principales apparaissent dans la première colonne après le total.

## L'interface de &karm;

La fenêtre principale de &karm; présente les composants suivants : barre de menus, barre d'outils, fenêtre de tâches et de durées et barre d'état.

L'écran de &karm; L'écran de &karm;

### La fenêtre de tâches et de durées

Les différentes tâches sont affichées dans cette fenêtre, avec le temps accumulé pour chacune dans la session en cours et au total. Celles actuellement en cours ont une icône en forme d'horloge à côté de la durée de la session.

Des sous-tâches peuvent être créées pour chaque tâche. Un clic sur les signes plus et moins, affiche ou cache celles qui sont associées. La durée totale pour la tâche inclut les durées de ses sous-tâches, ainsi que sa propre durée.

### La barre de menus de &karm;

#### Le menu Fichier

&Ctrl;S Fichier Enregistrer

- Enregistre les tâches et sous-tâches actuelles ainsi que leurs durées

&Ctrl;P Fichier Imprimer

- Imprime le contenu de la fenêtre de &karm;

Fichier Démarrer une nouvelle session

- Réinitialise toutes les durées de la session

Fichier Réinitialiser toutes les durées

- Réinitialise toutes les durées

Fichier Importer / exporter Importer un ancien fichier plat...

- Importe un enregistrement d'une ancienne version de &karm; (&karm; utilise maintenant le format iCalendar).

Fichier Importer / exporter Importer des tâches de Planner...

- Importe un projet de Planner. Toutes les tâches, sous-tâches et leurs états seront importés depuis le fichier. Vous pouvez les importer en tant que sous-tâches : créez en une, sélectionnez-la, puis importez.

Fichier Importer / exporter Exporter dans un fichier CSV...

- Exporte la Durée totale de la session, la Durée de la session, la Durée et la Durée totale dans un fichier texte.

Fichier Importer / exporter Exporter l'historique dans un fichier CSV...

- Exporte l'historique des tâches dans un fichier texte.

&Ctrl;C Fichier Copier les totaux dans le presse-papiers

- Copie la durée totale pour une ou toutes les tâches dans le presse-papiers de &kde;

&Ctrl;&Alt;C Fichier Copier l'historique dans le presse-papiers

- Copie les durées journalières sur une période donnée dans le presse-papiers de &kde;

&Ctrl;Q Fichier Quitter

- Ferme &karm;

#### Le menu Chronomètre

S Chronomètre Démarrer

- Démarre le chronomètre pour la tâche sélectionnée

Chronomètre Arrêter

- Arrête le chronomètre pour la tâche sélectionnée

&Echap; Chronomètre Arrêter tous les chronomètres

- Arrête les chronomètres de toutes les tâches

#### Le menu Tâches

&Ctrl;N Tâche Nouvelle

- Ajoute une nouvelle tâche

&Ctrl;&Alt;N Tâche Nouvelle sous-tâche

- Ajoute une nouvelle sous-tâche à la tâche sélectionnée

Suppr. Tâche Supprimer

- Supprime la tâche ou sous-tâche sélectionnée

&Ctrl;E Tâche Modifier

- Modifie le nom ou la durée accumulée pour la tâche courante

  Il y a deux options pour modifier les durées : Modifier les valeurs absolues, les durées totale et de session peuvent être changées séparément, et Modifier les valeurs relatives qui ajoute ou soustrait un nombre dans les deux catégories à la fois (session et totale).

  L'option de suivi automatique permet de démarrer et d'arrêter le chronomètre automatiquement lorsque vous changez de ou vers un bureau &kde; précis.

#### Le menu Configuration

Configuration Configurer les raccourcis claviers

- Ouvre une boîte de dialogue qui vous permet de modifier les raccourcis clavier

Configuration Configurer &karm;

- Ouvre une boîte de dialogue pour configurer &karm;

  La boîte de dialogue est divisée en trois catégories : Comportement, qui vous permet de spécifier un alerte en cas d'inactivité ainsi qu'un message d'alerte lorsque vous supprimez une tâche, Affichage, qui configure les champs à afficher dans la fenêtre principale et Stockage, qui paramètre l'emplacement du fichier d'enregistrement, si l'enregistrement se fait automatiquement et au bout de combien de temps.

#### Le menu Aide

&help.menu.documentation;

### La barre d'outils

La barre d'outils contient des icônes pour les commandes suivantes :

(Toutes ont le même comportement que dans les menus).

- Démarrer

- Arrêter

- Nouvelle

- Nouvelle sous-tâche

- Supprimer

- Modifier

### La barre d'état

Rapporte la durée totale écoulée pendant la session.

## Remerciements et licence

&karm;

Copyright du programme :

- 1997-2000 Sirtaj Singh Kang taj@kde.org.

- 2001-2002 Tomas Pospisek tpo_deb@sourcepole.ch

- 2003-2004 Mark Bucciarellimark@hubcapconsulting.com

Contributeurs (par ordre alphabétique)

- Allen Winter winterz@verizon.net

- David Faure faure@kde.org

- Espen Sand espen@kde.org

- Gioele Barabucci gioele@gioelebarabucci.com

- Jan Schaumann jschauma@netmeister.org

- Jesper Pedersen blackie@ifad.dk

- Kalle Dalheimer kalle@kde.org

- Klarälvdalens Datakonsult AB

- Mark Bucciarelli mark@hubcapconsulting.com

- Thorsten Stärk dev@staerk.de

- Tomas Pospisek tpo_deb@sourcepole.ch

- Willi Richert w.richert@cox.net

&karm; s'inspire de l'utilitaire de Harald Tveit Alvestrand nommé titrax, dont le seul défaut est d'être basé sur la boîte à outils Xt.

Copyright pour la documentation 2000-2004 Jonathan Singer jsinger@leeta.net et Sirtaj Singh Kang taj@kde.org.

&underFDL; &underGPL;
tâche active

Une tâche ayant un chronomètre actif.

&DCOP;

Le protocole de communication entre processus utilisé par KDE. Abréviation de Desktop COmmunication Protocol (Protocole de communication pour le bureau).

bureau

GNU/Linux, FreeBSD et les autres systèmes qui utilisent X-Windows ont plusieurs bureaux. En général, quatre bureaux sont accessibles par défaut. Chacun peut afficher ses propres programmes et fichiers. Au démarrage de KDE, le bureau que vous voyez s'appelle Bureau 1. Si vous faites &Alt;F2, vous verrez le Bureau 2. faites &Alt;F1 pour revenir au Bureau 1.

historique

Si &karm; est configuré pour conserver l'historique, il enregistrera tous les démarrages et arrêts des chronomètres. Cette historique n'est pas vider lorsque les compteurs sont réinitialisés et reste intact jusqu'à la suppression de la tâche.

session

Un point de départ défini par l'utilisateur pour les chronomètres de session. Une nouvelle session commence quand vous faites Fichier Démarrer une nouvelle session . Les données de la session ne sont pas enregistrées lorsque vous créez une nouvelle session.

Durée de la session

Le temps passé sur la tâche depuis le début de la session.

Boîte à miniatures

La boîte à miniatures est dans la barre qui apparaît (par défaut) en bas de l'écran. Dans cette boîte la miniature de &karm; se trouve complètement à droite.

tâche principale

Une tâche ne dépendant d'aucune autre.

Durée totale de la session

Le temps passé sur la tâche et toutes ses sous-tâches depuis le début de la session.

Durée

Le temps passé sur la tâche depuis la réinitialisation de tous les compteurs.

Durée totale

Le temps passé sur la tâche et toutes ses sous-tâches depuis la réinitialisation de tous les compteurs.

## Installation

### Comment obtenir &karm;

&install.intro.documentation; &install.compile.documentation;

## Interface &DCOP;

version

version

Renvoi la version de &karm;.

    QString version()

#### Description

`version()` est un appel &DCOP; qui renvoi le numéro de version de &karm; : par exemple 1.5.0. Ce numéro est renvoyé en tant que chaîne dans le format GNU habituel : majeure.mineure.correction.

quit

quit

Renvoi la fermeture de &karm;.

    QString quit()

#### Description

`quit()` est un appel &DCOP; qui donne la possibilité à un programme externe de fermer correctement &karm;.

hastodo

hastodo

Vérifie si une tâche principale existe.

    QString hastodo(QString nom_de_la_tâche)

#### Paramètres

`nom_de_la_tâche`

- Le nom de la tâche à chercher.

#### Description

`hastodo(QString nom_de_la_tâche)` est un appel &DCOP; qui recherche une tâche portant un nom précis. Si ce nom est trouvé, un UID iCalendar est renvoyé pour identifier cette tâche. Sinon, une chaîne vide est renvoyée.

C'est dans le fichier iCalendar utilisé actuellement par &karm; que la recherche est faites. Elle porte sur toute l'arborescence, pas seulement sur les tâches principales. Si plusieurs tâches correspondent, c'est la première trouvée qui est renvoyée.

addtodo

addtodo

Ajouter une nouvelle tâche.

    QString addtodo(QString tâche_à_ajouter)

#### Paramètres

`tâche_à_ajouter`

- Le nom de la tâche à ajouter.

#### Description

`addtodo(QString tâche_à_faire)` est un appel &DCOP; qui ajoute une tâche principale au fichier en cours d'utilisation. L'UID de la nouvelle tâche est renvoyé.

&documentation.index;