# Руководство &karm;

## Вступление

&karm; отслеживает время, затраченное на различные задачи. Это полезно для учёта оплаченного времени, или для учёта времени работы над отдельной задачей по дням.

Этот журнал времени может быть экспортирован в текстовый файл с запятыми в качестве разделителей для импорта в другие программы учёта и/или управления проектами.

&karm; определяет бездествие клавиатуры и мыши бездействуют, он может связывать различные задачи с разными рабочими столами.

&karm; была написана Сиртаем Сингх Кангом (Sirtaj Singh Kang). Слово karm в переводе с пенджаби (родной язык автора) означает работа.

## Использование &karm;

### Запуск &karm;

Введите `karm` в командной строке или выберите Учёт рабочего времени из группы Утилиты (Служебные) главного меню KDE. Доступны стандартные ключи &Qt; и &kde;, их можно просмотреть, введя ``karm` `--help`` в командной строке.

&karm; предоставляет дополнительный командный параметр, позволяющий вам ввести имя файла iCalendar, в котором хранится журнал вашей работы. Имя удалённого файла iCalendar вводится с добавлением префикса http или ftp, например, http://www.mysite.com/mydata/mylabor.ics.

### Задачи

Ситуация: Вы консультант по свободному ПО, у вас много клиентов. У некоторых из них по нескольку проектов. В течение дня вам приходится постоянно переключаться между ними. Вам необходим учёт времени, на основе которого вы хотите ежемесячно предъявлять к оплате счета.

Решение: Создайте по одной задаче высшего уровня для каждого клиента и по подзадаче для каждого из клиентских проектов. Для каждого проекта, требующего более детального учёта, создайте группу подзадач в каждом проекте. Отмечайте время двойным щелчком на каждой задаче, над которой работаете в данный момент.

&karm; позволяет отслеживать неограниченное количество задач и подзадач любой глубины вложенности. Можно учитывать выполнение одной задачи, или одновременно нескольких.

Для того чтобы создать задачу высшего уровня, вызовите пункт меню &Ctrl;N Задача Создать Для создания подзадачи выберите родительскую задачу и вызовите &Ctrl;&Alt;N Задача Создать подзадачу

При закрытии &karm; список задач сохраняется в файле, указанном в Настройка Настроить KArm . При следующем запуске список задач обновляется из этого файла.

&karm; может импортировать и экспортировать задачи. См. Прочие системы.

### Таймеры

Ситуация: Чтобы оставаться платежеспособным, вам необходимо работать в среднем пять часов в день. Нужен ежедневный и еженедельный учёт.

Решение: Сбрасывайте таймер сеанса в начале каждого рабочего дня, и все таймеры - в начале каждой недели.

&karm; упрощает учёт времени. Для запуска учёта времени, потраченного на определённую задау, щёлкните дважды на ней. Для остановки учёта щёлкните дважды на задаче ещё раз. Активные задачи отображаются маленькими значками в столбце Время сеанса.

Ещё один компонент интерфейса &karm; - значок в системном лотке. Когда задача активна, вторая рука в значке движется. Если навести указатель мыши на этот значок, название активной задачи отобразится во всплывающей подсказке. Если активных задач несколько, их названия будут разделены запятыми.

Для каждой задачи &karm; ведёт по два таймера - один подсчитывает время сеанса, другой - общее время. По умолчанию &karm; отображает по два столбца для каждого таймера, в итоге каждой задаче отводится четыре столбца.

Время сеанса

- Время, затраченное на задачу с начала сеанса.

Общее время сеанса

- Время, затраченное на задачу со всеми её подзадачами с начала сеанса.

Время

- Время, затраченное на задачу с момента обнуления всех таймеров.

Общее время

- Время, затраченное на задачу со всеми её подзадачами с момента обнуления всех таймеров.

Для того чтобы начать новый сеанс, выберите Файл Начать новый сеанс

Чтобы обнулить все таймеры, выберите Файл Обнулить все таймеры

#### Учёт времени на разных рабочих столах

Ситуация: У вас есть два основных проекта, над которыми вы ежедневно работаете. Разумно организовав свою работу, вы держите файлы проекта 1 на Рабочем столе 1, а файлы проекта 2 на Рабочем столе 2.

Решение: Свяжите задачу проекта 1 с Рабочим столом, а задачу проекта 2 с Рабочим столом 2. Когда вы переключитесь с одного рабочего стола на другой, &karm; автоматически переключит учёт времени задач.

Для того чтобы связать задачу с одним или больше Рабочими столами, выберите &Ctrl;E Задача Правка Включите Автоматическое отслеживание и выберите Рабочий стол или столы, с которыми хотите связать задачу. Когда любой из выбранных столов станет активным, после недолгой задержки &karm; начнет отсчет времени данной задачи.

#### Учёт бездействия

Ситуация: Вы ушли с работы в пятницу пораньше и уехали на все выходные, забыв выключить таймер. При вашем возвращении в понедельник таймер все ещё работает.

Решение: Включите учёт бездействия.

&karm; может определять бездействие ваших мыши и клавиатуры. Если они не подают сигналы дольше определённого количества минут, &karm; выдаст следующий диалог:

&karm; Определение простоя Окно Определение простоя &karm;

Сбросить и остановить

- Вычитает время бездействия из всех активных таймеров и останавливает их.

  Вы не работали над задачей (задачами) во время бездействия компьютера, и не работаете до сих пор.

Сбросить и продолжить

- Вычитает время бездействия из всех активных таймеров, но оставляет их в работе.

  Вы не работали над задачей, пока ваш компьютер простаивал, но сейчас работаете.

Продолжить отсчёт

- Добавляет время простоя ко всем активным таймерам и оставляет их в работе.

  Вы работали над задачей во время простоя компьютера, и продолжаете работу.

### Создание отчётов

&karm; предоставляет три разных способа получения отчёта о времени работы. Можно распечатать отчёт о длительности сеансов и общем времени работы на принтере; скопировать общий отчёт или журнал в буфер обмена.

#### Распечатка отчётов

Для того чтобы вывести общий отчёт на печать, вызоваите &Ctrl;P Файл Печать Будет создан отчёт из трёх столбцов, содержащий данные обо всех задачах. В первом столбце будет содержаться название задачи, во втором Общее время сеанса, и в третьем - Общее время.

#### Помещение отчёта в буфер обмена

Для того чтобы создать итоговый отчёт в буфере обмена, выберите &Ctrl;C Файл Копировать итоги в буфер обмена.

Этот отчёт создаётся для выбранной задачи и всех её подзадач. Если текущая задача имеет родительскую, &karm; задаст вопрос о том, хотите ли вы создать отчёт только для текущей задачи и всех её подзадач, или для всех задач вообще.

&karm; Копировать данную задачу &karm; Копировать диалог данной задачи

Когда отчёт будет готов, откройте KEdit или другой текстовый редактор, и вставьте данные отчёта.

    Task Totals
    2004-07-10 02:26

      Time    Task
    ----------------------------------------------
      9:14    kde
       9:14    karm
        1:08    bugs
        0:00    checkin changes
       0:00    promo
       0:00    web stuff
    ----------------------------------------------
      9:14 Total

В первом столбце указано Общее время и сделаны отступы, с тем чтобы показать зависимость между задачами и подзадачами. Отчёт о времени включает данные о подзадачах.

#### Помещение журнала в буфер обмена

Для создания отчёта в буфере обмена, выберите &Ctrl;&Alt;C Файл Копировать историю в буфер обмена.

Необходимо поставить отметку возле переключателя Вести журнал в Настройка Настроить KArm . Иначе &karm; сохранит только итоговые, а не детальные данные журнала.

Этот отчёт составляется только для данной конкретной задачи и её подзадач. В отличие от общего отчёта, этот не дает возможности получить данные обо всех задачах из списка.

Если вы выберете отчёт в форме журнала, &karm; попросит ввести диапазон данных:

&karm; введите диапазон данных &karm; введите диапазон данных

После ввода диапазона данных, откройте любой текстовый редактор и вставьте в него отчёт.

    Task History
    From Thursday 01 July 2004 to Monday 12 July 2004
    Printed on: 2004-07-12 17:18

                                   Week of Monday 05 July 2004
         5     6     7     8     9    10    11
    -------------------------------------------------------------------------
                                                 0:00 kde
                                                 0:00  dc
                  !:22  1:46  3:14  1:44         8:06  karm
                                                 0:00   3.2 feature plan
                  1:08                           1:08   bugs
                                                 0:00   checkin changes
                                                 0:00  promo
                                                 0:00  web stuff
    -------------------------------------------------------------------------
                  2:30  1:46  3:14  1:44         9:14 Total

Журнал задач группирует данные по дням и задачам, подводя итог еженедельно. Первые семь столбцов представляют дни недели, восьмая даёт недельный итог, а в девятой указано название задачи. Названия смещены с учётом иерархии задач и подзадач.

### Прочие системы

#### KOrganizer

&karm;, как KOrganizer и iCal из Apple, использует для хранения данных общепризнанный стандартный формат iCalendar. &karm; может обрабатывать файлы, созданные этими программами.

Если один и тот же файл открыт в &karm;, и в KOrganizer, то, редактируя его в KOrganizer, вы рискуете потерять данные. Безопаснее редактировать файл только в одном из приложений.

#### Planner

Как часто бывает, вам может понадобиться спланировать работу над проектом с помощью инструмента управления проектами Imendio Planner (от planner.imendio.org) и импортировать его задачи в &karm;, чтобы привести их к общепризнанному стандартному формату iCalendar. Сделав это, вы сможете составить расписание задач в KOrganizer и вести их учёт в &karm;. В этом случае вы будете уверены в том, что уложитесь в данные время и бюджет.

#### &DCOP;

&DCOP; - это механизм, при помощи которого программы KDE взаимодействуют друг с другом. KDE-программы предоставляют ряд функций, которые можно вызывать из других программ (например, из сценариев Bash).

##### Сценарий Bash, возвращающий версию &karm;

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

Нынешний интерфейс &karm; с &DCOP; используется в основном для автоматического тестирования, поэтому весьма ограничен. Полное описание интерфейса здесь: Приложение: Интерфейс &DCOP;.

Для просмотра полного интерфейса &DCOP; для версии &karm;, установленной в вашей системе, выполните следующий сценарий Bash:

##### Вывод интерфейса &karm; с &DCOP; на консоль

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

#### Экспорт отчёта в CSV

&karm; может экспортировать как отчёт, так и журнал в файл с разделителями-запятыми. Для экспорта отчёта вызовите пункт меню Файл Импорт/Экспорт Экспорт в файл CSV ... , и &karm; выведет следующий диалог:

&karm;: Диалог экспорта в CSV &karm;: Диалог экспорта в CSV

Укажите имя файла, в который вы желаете экспортировать данные и измените другие параметры диалога, если это необходимо. Заметьте, что контроль над диапазоном данных возможен только, если вы экспортируете данные журнала, а не общий отчёт. Нажмите Экспорт, и &karm; экспортирует данные отчёта о времени всех задач в выбранный вами файл.

Вот пример вывода:

    "kde",,,,,0.00,0.00,6.88,9.83
    ,"karm",,,,6.88,8.70,6.88,9.83
    ,,"3.2 feature plan",,,0.00,0.00,0.00,0.00
    ,,"bugs",,,0.00,1.13,0.00,1.13
    ,,"checkin changes - translation strings",,,0.00,0.00,0.00,0.00
    ,,"time card report",,,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 stuff",,,,0.00,0.00,0.00,0.00

Задачи высшего уровня выведены в первой колонке, подзадачи во второй, и т.д. Хронологические данные выведены после максимальной глубины задач (в нашем случае глубина равна пяти). Первая временная колонка представляет Время сеанса, вторая Время, третья Общее время сеанса, и четвёртая Общее время.

#### Экспорт журнала в CSV

Для того чтобы экспортировать журнал задач, вызоваите пункт меню Файл Импорт/Экспорт Экспорт журнала в файл CSV , и &karm; выведет тот же диалог, что мы видели выше.

Укажите имя файла, в который хотите экспортировать журнал и укажите диапазон данных для журнала. Измените прочие параметры диалога, если нужно. Нажмите Экспорт, и &karm; экспортирует журнал задач в указанный файл.

Вот пример вывода:

    Task History
    From Tuesday 06 July 2004 to Tuesday 13 July 2004
    Printed on: 2004-07-13 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 feature plan"
    ,1.13,,,,,,,1.13,,,"bugs"
    ,,,,,,,,0.00,,,"checkin changes - translation strings"
    ,,,,,,,,0.00,,,"time card report"
    ,,,,,,,,0.00,,"kopete"
    ,,,,,,,,0.00,,"promo"
    ,,,,,,,,0.00,,"web stuff"

Три строки указывают, когда и для какого диапазона данных был создан этот отчёт. Четвертая строка представляет разделенный запятыми список дат в диапазоне данных в формате ISO 8601 (YYYY-MM-DD). В последующих строках указано время выполнения для каждой задачи. Последняя колонка чисел есть общий итог за все дни. Названия задач отображаются за итоговой колонкой, они смещаются для отображения связей задач с подзадачами. Задачи высшего уровня отображаются сразу за итоговой колонкой.

## Интерфейс &karm;

Главное окно &karm; содержит следующие элементы: меню, панель инструментов, окно Задача/Время и строку состояния.

Экран &karm; Экран &karm;

### Окно Задача/Время

В этом окне отображены различные задачи и время, затраченное на их выполнение в текущем сеансе и в целом. Задачи, для которых ведётся хронометраж в данный момент, обозначены маленьким значком с изображением часов рядом со временем сеанса.

Для каждой задачи могут создаваться подзадачи. Двойной щелчок на задаче показывает или скрывает её подзадачи. Общее время, затраченное на задачу, включает в себя время всех её подзадач и её собственное.

### Меню &karm;

#### Меню Файл

&Ctrl;S Файл Сохранить

- Сохраняет данные о времени, затраченном на текущие задачи и подзадачи

&Ctrl;P Файл Печать

- Выводит на печать окно &karm;

Файл Начать новый сеанс

- Обнуляет все хронометры сеанса

Файл Обнулить все таймеры

- Обнуляет все таймеры

Файл Импорт/Экспорт Импорт файла устаревшего формата

- Импортирует файлы старых версий &karm; (новый формат - iCalendar-style.)

Файл Импорт/Экспорт Импорт задач из Planner...

- Импортируетпроект imendio Planner (смотрите planner.imendio.org). Все задачи и подзадачи можно импортировать из .planner-файла полностью. Можно импортировать их как подзадачу, создав подзадачу, оставив её помеченной, а затем импортировав.

Файл Импорт/Экспорт Экспорт в файл CSV-файл...

- Экспортирует Общее время сеанса, Время сеанса, Время и Общее время в текстовый файл.

Файл Импорт/Экспорт Экспорт журнала в CSV-файл...

- Экспортирует журнал задач в текстовый файл.

&Ctrl;C Файл Копировать отчёт в буфер обмена

- Копирует текущие значения в буфер обмена &kde;

&Ctrl;&Alt;C Файл Копировать журнал в буфер обмена

- Копирует статистику за указанный период в буфер обмена

&Ctrl;Q Файл Выход

- Закрывает &karm;

#### Меню Отсчет

S Отсчет Пуск

- Запускает счетчик для выбранной задачи

Отсчет Остановить

- Останавливает счетчик для выбраной задачи

&Esc; Отсчет Остановить все хронометры

- Останавливает счётчики всех задач

#### Меню Задача

&Ctrl;N Задача Создать

- Добавляет новую задачу

&Ctrl;&Alt;N Задание Создать подзадачу

- Добавляет новую подзадачу к выбранной задаче

Del Задание Удалить

- Удаляет выбранную задачу или подзачу

&Ctrl;E Задание Изменить

- Изменяет имя или затраченное время для выбранной задачи

  Есть два варианта изменения значения времени: "абсолютное изменение", в котором сеансы и времена могут быть изменены по отдельности, и "относительное изменение", в котором изменение добавляется или удаляется и из времени сеанса, и из общего времени.

  Параметр Автохронометраж позволяет включать и выключать хронометр в зависимости от текущего Рабочего стола &kde;.

#### Меню Настройка

Настройка Настроить горячие клавиши

- Открывает окно для задания горячих клавиш

Настройка Настроить KArm

- Открывает окно для изменения конфигурации &karm;

  Диалог имеет три вкладки: Поведение , в котором можно указать уведомление при отсутствии активности и предупреждение перед удалением комплекта задач, Вид, в котором настраиваются поля, отображаемые в главном окне и Хранилище, в котором можно указать путь для сохранения файлов по умолчанию при автосохранении, включить его и задать его интервал.

#### Меню Справка

&help.menu.documentation;

### Панель инструментов

Панель содержит значки следующих команд:

(Все они действуют идентично меню команд.)

- Пуск

- Стоп

- Создать

- Создать подзадачу

- Удалить

- Изменить

### Строка состояния

Показывает полное время сеанса.

## Благодарности и Лицензия

&karm;

Авторские права на программу:

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

- 2001-2002 Tomas Pospisek tpo_deb@sourcepole.ch

- 2003-2004 Mark Bucciarellimark@hubcapconsulting.com

Соавторы (в алфавитном порядке)

- 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; навеяна очень полезной утилитой под названием titrax, единственный недостаток которой состоит в том, что она основана на создана с помощью инструментария Xt.

Documentation copyright 2000-2004 Jonathan Singer jsinger@leeta.net and Sirtaj Singh Kang taj@kde.org.

&underFDL; &underGPL;
активная задача

Задача, таймер которой сейчас включен.

&DCOP;

Протокол межпроцессовых связей, используемый в KDE. Short for Desktop COmmunication Protocol.

рабочий стол

В GNU/Linux, FreeBSD и других системах, которые используют X-Windows, может быть не один Рабочий стол, по умолчанию их четыре. На каждом Рабочем столе можно работать с отдельным набором программ и файлов. Когда KDE запускается впервые, вы видите Рабочий стол 1. Нажав &Alt;F2, можно перейти на Рабочий стол 2. Нажатие &Alt;F1 приведет нас обратно на Рабочий стол 1.

журнал

Если &karm; настроен на ведение журнала, он будет регистрировать каждый случай включения/выключения таймера. Этот журнал никогда не стирается со времени обнуления таймеров, и остается в файле до самого удаления задачи.

сеанс

Определяемая пользователем точка отсчета для таймеров сеанса. Новый сеанс начинается при выборе пункта Файл Начать новый сеанс. Когда начинается новый сеанс, сеансовые данные не обнуляются.

Время сеанса

Время, затраченное на задачу с начала сеанса.

системный лоток

Системный лоток находится в панели, которая (по умолчанию) находится внизу экрана. В системном лотке значок &karm; крайний справа.

задача высшего уровня

Задача, у которой нет родительских задач.

Общее время сеанса

Время, затраченное на задачу со всеми её подзадачами с начала сеанса.

Время

Время, затраченное на задачу с момента обнуления всех таймеров.

Общее время

Время, затраченное на задачу со всеми её подзадачами с момента обнуления всех таймеров.

## Установка

### Как получить &karm;

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

## Интерфейс &DCOP;

version

version

Возврат версии &karm;.

    QString version()

#### Описание

`version()` - это вызов &DCOP;, возвращающий номер версии &karm;, например 1.5.0. Номер версии возвращается в виде строки типичного GNU-формата major.minor.bugfix.

quit

quit

Возвращает выход из &karm;.

    QString quit()

#### Описание

`quit()` - это вызов &DCOP;, который дает возможность внешним программам аккуратно завершить работу &karm;.

hastodo

hastodo

Проверка наличия задачи высшего уровня.

    QString hastodo(QString taskname)

#### Параметры

`taskname`

- Название искомой задачи.

#### Описание

`hastodo(QString taskname)` - это вызов &DCOP; для поиска по данному имени. Если имя будет найдено. будет возвращен идентификатор файла iCalendar, относящегося к этой задаче. Если же имя не найдено, вернется пустая строка.

Файл iCalendar, который &karm; откроет, и есть искомый файл. Будет найдена не только задача высшего уровня, но и все дерево процессов. Если несколько задач имеют одинаковые названия, будет возвращена первая из найденных.

addtodo

addtodo

Добавить новую задачу.

    QString addtodo(QString todoname)

#### Параметры

`todoname`

- Название новой задачи.

#### Описание

`addtodo(QString todoname)` - это вызов &DCOP;, который добавляет новую задачу высшего уровня к текущему комплекту. Возвращает идентификатор новой задачи.

&documentation.index;