.. -*- coding: UTF-8 -*-

========================
Como usar ``Tempômetro``
========================

Introdução
==========

Tempômetro é um conjunto de pequenos scripts em Python usado para facilitar a 
mensuração do tempo gasto em desenvolvimento, estudo, composição de textos etc. 
de maneira análoga a programas como PSPLog_.

.. _PSPLog: http://www.ipd.uka.de/mitarbeiter/muellerm/PSP/

Atualmente, temos dois scripts: ``timer.py`` e ``report.py``, usados 
respectivamente para registrar começo, fim e interrupções na tarefa e para
gerar estatísticas muito básicas a partir dos dados entrados.

Como utilizar
=============

Utilizar os *scripts* é simples. Primeiro, vamos aprender a utilizar o 
*timer.py*, assumindo-se que ele esteja no *path* dos programas (onde ele não 
precisa estar).

Para começar, precisamos criar uma tarefa. Suponha que estejamos fazendo uma 
aplicação, e a estejamos modelando agora. Começaremos a tarefa de modelagem 
assim::

    $ timer.py task "Modelagem da aplicação"

Isto apenas informa que uma nova tarefa foi criada. Precisamos explicitamente 
iniciar a seção de trabalho logo após isto::

    $ timer.py start

Suponha que tenhamos de interromper as atividades cinco minutos depois. 
Reportamos isto com o comando ``interrupted``::

    $ timer.py interrupt

Assim que voltarmos ao trabalho, declaramos que estamos retornando assim::

    $ timer.py return

Agora, vamos dormir. Então encerramos esta seção, após mais dez minutos de 
trabalho (totalizando quinze minutos)::

    $ timer.py stop

Para ver quanto tempo nós gastamos, apenas chamamos o *script* ``report.py``::

    $ report.py
    Task "Modelagem da aplicação": 0:15
    Total: 0:15

No dia seguinte, você pode voltar e iniciar novamente o trabalho na mesma 
tarefa com o comando ``timer.py start``.

Você só pode chamar ``report.py`` quando todos os ciclos de trabalho estão 
fechados - i. e., depois de chamar ``timer.py stop``. Note também que nenhum 
erro será lançado se você chamar, digamos, ``timer.py start`` duas vezes em 
seqüência, ou qualquer coisa neste formato. Os erros só aparecerão ao se chamar 
``report.py`` - e as mensagens não serão bonitas... 

``TimeLog``
===========

Todos os comandos processam o arquivo ``TimeLog`` localizado no diretório 
corrente.

Este arquivo é formado por vários conjuntos de linhas. Cada conjunto começa
com uma linha na forma::

    <ano>-<mês em dois dígitos>-<dia>: Task "<nome da tarefa>" started

à qual podem se seguir zero ou mais linhas. Um exemplo desta linha é::

    2007-03-04: Task "Example" started

Se houver uma linha logo após
a primeira linha no formato acima, ela deve ter o formato::

    <ano>-<mês em dois dígitos>-dia: started at <hora>:<minuto>

sinalizando a hora em que o trabalho começou. Por exemplo::

    2007-03-10: started at 00:32

A uma linha "started" pode se seguir uma linha "stopped", na forma

::

    <ano>-<mês em dois dígitos>-dia: stopped at <hora>:<minuto>

ou uma linha "interrupted", na forma

::

    <ano>-<mês em dois dígitos>-dia: interrupted at <hora>:<minuto>

Uma linha "stopped" sinaliza que o trabalho foi encerrado, por ora. Já uma 
linha "interrupted" informa que o usuário interrompeu o trabalho 
momentaneamente. À uma linha "interrupted" num arquivo "completo" deve se
seguir uma linha "returned" na forma

::

    <ano>-<mês em dois dígitos>-dia: returned at <hora>:<minuto>

à qual só se podem seguir, evidentemente, linhas "interruped" ou "stopped".

Depois de uma linha "stopped", podem se seguir várias linhas seguindo o mesmo 
padrão acima. Também pode se seguir outra linha na forma

::

    <ano>-<mês em dois dígitos>-<dia>: Task "<nome da tarefa>" started

e assim por diante.