view release on metacpan or  search on metacpan

lib/App/JobLog/Command/info.pm  view on Meta::CPAN

}

sub _header {
    my ( $self, $executable ) = (@_);
    return <<END;
==head1 Job Log

work log management

version @${[ $App::JobLog::Command::info::VERSION // 'DEVELOPMENT' ]}

This application allows one to keep a simple, human readable log
of one's activities. B<Job Log> also facilitates searching, summarizing,
and extracting information from this log as needed.
END
}

sub _body {
    my ( $self, $executable ) = (@_);
    return $self->_basic_usage($executable) . $self->_advanced_usage();
}

sub _basic_usage {
    my ( $self, $executable ) = (@_);
    return <<END;

==head1 Usage

B<Job Log> keeps a log of events and notes. If you begin a new task you type

   $executable @{[App::JobLog::Command::add->name]} what I am doing now

and it appends the following, modulo changes in time, to @{[log]}:

   2011 2 1 15 19 12::what I am doing now

The portion before the first colon is a timestamp in year month day hour minute second format.
The portion after the second colon is your description of the event.

If you wish to take a note, you type

   $executable @{[App::JobLog::Command::note->name]} something I should remember

and it appends the following to @{[log]}:

   2011 2 1 15 19 12<NOTE>:something I should remember

Again, the portion before the first colon is a timestamp. The portion after the E<lt>NOTEE<gt> is
the body of the note.

The text between the two colons, or between the first colon and the E<lt>NOTEE<gt> tag, which is blank in these
examples, is a list of space-delimited tags one can use to categorize things. For
instance, if you were performing this task for Acme Widgets you might have typed

   $executable @{[App::JobLog::Command::add->name]} -t "Acme Widgets" what I am doing now

producing

   2011 2 1 15 19 12:Acme\\ Widgets:what I am doing now

Note the I<\\> character. This is the escape character which neutralizes any special value of
the character after it -- I<\\>, I<:>, or a whitespace character.

You may tag an event multiple times. E.g.,

   $executable @{[App::JobLog::Command::add->name]} -t "Acme Widgets" -t foo -t bar what I am doing now

producing

   2011 2 1 15 19 12:Acme\\ Widgets foo bar:what I am doing now

For readability it is probably best to avoid spaces in tags.

Since one usually works on a particular project for an extended period of time, if you specify no tags
the event or note is given the same tags as the preceding event/note. For example,

   $executable @{[App::JobLog::Command::add->name]} -t foo what I am doing now
   $executable @{[App::JobLog::Command::add->name]} now something else

would produce something like

   2011 2 1 15 19 12:foo:what I am doing now
   2011 2 1 16 19 12:foo:now something else

When you are done with the last task of the day, or your stop to take a break, you type

   $executable @{[App::JobLog::Command::done->name]}

which adds something like

   2011 2 1 16 19 12:DONE

to the log. Note the single colon. In this case I<DONE> is not a tag. Tags are always sandwiched between
two delimiters. I<DONE> here just marks the line as the end of a task.

When you come back to work you can type

   $executable @{[App::JobLog::Command::resume->name]}

to add a new line to the log with the same description and tags as the last task you began.

==head2 Summary Commands

The log is of little use if you cannot extract useful reports of what it contains. For this there are a
variety of commands.

==over 8

==item B<@{[App::JobLog::Command::summary->name]}>

The most extensive and featureful log report command. Example:

 \$ job summary yesterday
 Monday, 14 March
    9:46 - 10:11 am  0.41  widgets  modifying name normalization code to use dates
   10:17 - 10:55 am  0.62  widgets  modifying name normalization code to use dates
     1:49 - 2:08 pm  0.32  widgets  testing PGA file to see whether Felix Frankfurter is still there

   TOTAL HOURS 1.35
    widgets    1.35