Read Me

metadiary is a quick and easy to use diary.

metadiary is designed so you can easily tag your calendar with your
activities, and then it helps you to understand how much time you
spend on them.

To build and use metadiary, first edit the Makefile and eventually
change some of the user configuration variables, then run make, and
invoke the program passing it a metadiary data file as argument, for
example:

	tar zxf metadiary-whatever.tar.gz
	cd metadiary-whatever
	vi Makefile # do change what eventually needed
	make
	cp example-metadiary.txt metadiary.txt
	./metadiary metadiary.txt

When the program will start, you will be presented the years view: it
is a view containing one cell for every year. You can move to the year
you want by using the arrow keys, the pageup/pagedown keys, and the
home/end keys. You can distinguish the year at point because the
background/foreground of its label are inverted. Now, press the enter
key to view the year at point.

You will be presented with the year view, it works like the years
view. Now, press the enter key to view the month at point.

You will be presented with the month view, it works like the year
view. Move to the desired day and press enter.

The day view will open. There are two main rectangles. In the upper
rectangle there are the activities. You can cycle between the
activities by pressing the tab key or the shift+tab combination for
cycling backward. In the rectangle containing the rest of the window
there is one cell for every quarter hour of the day.  You can change
the quarter hour at point like you moved in the month and year views.
For selecting more quarter hours, press shift while moving the point.

For assigning an activity to a quarter hour, press enter, and the cell
will be colored with the color pertaining to the activity.

You can return to the upper view by pressing the ESC key. If you press
the ESC key in the years view, the program will save the datafile and
exit.

For adding or modifying an activity, or an amount of time, edit the
metadiary datafile (for example a copy of example-metadiary.txt) by
using a text editor of our choice.

The metadiary.txt file has a simple format:

<KEYWORD> [PARAMETER]...

Please note the first line:
       howmany-activities 12

If you are going to add or to delete activities, then you have to keep
this value updated.

The following lines describe the activities, in this format:
    activity ID "LABEL" R G B
for example:
    activity 4 "hacking" 255 0 0

The ID value can be any decimal number, but the number 0 is used for
the special `unknown' activity, which is the default value for your
time for as long as you don't assign an activity to it, so it is not
recommended to use the zero id. Pay attention to not duplicate IDs.

The R G B values contain the decimal values for the Red Green and Blue
components which will determine the color associated to the
activity.

You can change the order of the activities by changing the order of
appearance in the datafile, but you don't want change the IDs,
remember that the IDs are used to link amount of times to the
activities, so you don't want to mess with them. For example this is
my datafile after having reordered the activities:

  howmany-activities 12
  activity 0 "unknown" 124 124 124
  activity 6 "sleeping" 111 111 255
  activity 9 "wash/eat" 175 175 255
  activity 1 "working" 245 0 245
  activity 2 "hacking" 255 0 0
  activity 7 "gym" 255 175 0
  activity 3 "studying" 255 255 0
  activity 4 "family time" 175 255 0
  activity 5 "friends time" 0 200 50
  activity 8 "organize/order" 0 255 210
  activity 11 "news" 175 255 255
  activity 12 "entertainment" 255 255 255

If you want to add a year, increase the value for this parameters:
   howmany-years-strings NUMBER_OF_STRINGS_DESCRIBING_THE_YEARS
   howmany-years NUMBER_OF_YEARS
for example:
   howmany-years-strings 4
   howmany-years 4

then, add the following line to the end of the datafile:
    year-string "2014"

then, add the internal description of the year:
    year NUMBER_OF_MONTHS
usually:
    year 12

then, for the first month, you will need to add the description of the month:
    month NUMBER_OF_DAYS
for example:
    month 31

followed by NUMBER_OF_DAYS amount of lines describing every day:
    day NUMBER_OF_SUBDAYS ACTIVITY_ID*NUMER_OF_SUBDAYS_FOR_ACTIVITY
for example:
    day 96 0x96

finally you have to repeat the two previous steps for all the remaining months.


Follows a description of all the keywords expected in a datafile:

howmany-activities NUMBER_OF_ACTIVITIES

  Declare the number of activities.

activity ID "LABEL" RED GREEN BLUE

  Define an activity.

  ID is a unsigned integer and will be used to store the activity in
  the time units. You should never change it if you are not sure of
  what you are doing, or your datafile may become useless.

hres HORIZONTAL_RESOLUTION

  Horizontal size of the window, in pixels (unsigned integer).

vres VERTICAL_RESOLUTION

  Vertical size of the window, in pixels (unsigned integer).

depth COLOR_DEPTH

  Color palette depth, in bits (unsigned int). For example, 8, 16, 24, 32.

mainloop-step MILLISECONDS

  The program will refreshed the window and check for events once
  every MILLISECONDS (unsigned integer).

actrect-height-part DENOMINATOR

  The activities rectangle height will be 1/DENOMINATOR (which is an
  unsigned integer) the height of the window.

actrect-lines LINES

  The activities will be showed in LINES number of lines (unsigned int)

dayrect-lines LINES

  The subday timeframes will be showed in LINES number of lines (unsigned int).

monthrect-lines LINES

  The days will be showed in LINES number of lines (unsigned int).

yearrect-lines LINES

  The months will be showed in LINES number of lines (unsigned int).

yearsrect-lines LINES

  The years will be showed in LINES number of lines (unsigned int).

fgcolor RED GREEN BLUE

  Foreground color. RED, GREEN and BLUE are RGB components (unsigned
  integers greater or equal to zero and lesser than 256).

bgcolor RED GREEN BLUE

  Background color. RED, GREEN and BLUE are RGB components (unsigned
  integers greater or equal to zero and lesser than 256).

  If it is equal to the fgcolor, then the bgcolor treated as transparent.

pointercolor RED GREEN BLUE

  Border color for selected elements. RED, GREEN and BLUE are RGB
  components (unsigned integers greater or equal to zero and lesser
  than 256).

backcolor RED GREEN BLUE

  Border color for unselected elements. RED, GREEN and BLUE are RGB
  components (unsigned integers greater or equal to zero and lesser
  than 256).

borders-numerator NUMERATOR
borders-denominator DENOMINATOR

  Border size is equal to NUMERATOR / DENOMINATOR multiplied for the
  size of the surrounded object.

howmany-weekdays NUMBER_OF_WEEKDAYS

  The number of week days. Set this to 7.

howmany-first-weekday-for-year NUMBER_OF_FIRST_WEEKDAY_FOR_YEAR_DESCRIPTORS

  One for every year.

first-weekday-for-year WEEKDAY_ID

  The week day for the first day of the year.
  0 = sunday, 1 = monday, ... 6 = saturday

howmany-year-strings NUMBER_OF_STRINGS_DESCRIBING_YEARS

  One for every year.

year-string "LABEL"

  The label for a year.

howmany-month-strings NUMBER_OF_STRINGS_DESCRIBING_MONTHS

  The number of defined month strings.

month-string "LABEL"

  The label for a month.

howmany-day-strings NUMBER_OF_STRINGS_DESCRIBING_DAYS

  The number of defined day strings.

day-string "LABEL"

  The label for a day.

howmany-subday-strings NUMBER_OF_STRINGS_DESCRIBING_SUBDAYS

  The number of defined subday strings.

subday-string "LABEL"

  The label for a subday timeframe.

cmaps-width WIDTH

  Width of the character maps.

cmaps-height HEIGHT

  Height of the character maps.

cmaps-index "SEQUENCE_OF_CHARACTERS"

  A string containing a sequence of all the mapped characters.

cmap "MAP"

  A map for a character. Newlines change the line. Other whitespace is
  skipped. Non-whitespace is painted if the foreground color.

current-year NUMBER
current-month NUMBER
current-day NUMBER
current-subday NUMBER
mark-subday NUMBER
mark-subday-is-active ZERO_OR_NONZERO
current-activity NUMBER
zoom ZERO_OR_ONE_OR_TWO_OR_THREE

  Keywords used for recording the user position in the program.

howmany-years NUMBER_OF_YEARS
year NUMBER_OF_MONTHS
month NUMBER_OF_DAYS
day NUMBER_OF_SUBDAYS ACTIVITY_ID*NUMBER_OF_SUBDAYS_FOR_ACTIVITY ...

  These keywords were described earlier in this document.


Please send bug-reports and suggestions or comments to:
  marco@marcoparrone.com