doc: commit a missing nroff file

hledger-lib/hledger_timedot.5

@@ -0,0 +1,147 @@
+
+.TH "hledger_timedot" "5" "February 2016" "" "hledger User Manuals"
+
+
+
+.SH NAME
+.PP
+hledger_timedot \- time logging format
+.SH DESCRIPTION
+.IP \[bu] 2
+toc
+.PP
+Timedot is a plain text format for logging dated, categorised quantities
+(eg time), supported by hledger.
+It is convenient for approximate and retroactive time logging, eg when
+the real\-time clock\-in/out required with a timeclock file is too
+precise or too interruptive.
+It can be formatted like a bar chart, making clear at a glance where
+time was spent.
+.PP
+Though called "timedot", the format does not specify the commodity being
+logged, so could represent other dated, quantifiable things.
+Eg you could record a single\-entry journal of financial transactions,
+perhaps slightly more conveniently than with hledger_journal(5) format.
+.SS Format
+.PP
+A timedot file contains a series of day entries.
+A day entry begins with a date, and is followed by category/quantity
+pairs, one per line.
+Dates are hledger\-style simple dates (see hledger_journal(5)).
+Categories are hledger\-style account names, optionally indented.
+There must be at least two spaces between the category and the quantity.
+Quantities can be written in two ways:
+.IP "1." 3
+a series of dots (period characters).
+Each dot represents "a quarter" \- eg, a quarter hour.
+Spaces can be used to group dots into hours, for easier counting.
+.IP "2." 3
+a number (integer or decimal), representing "units" \- eg, hours.
+A good alternative when dots are cumbersome.
+(A number also can record negative quantities.)
+.PP
+Blank lines and lines beginning with #, ; or * are ignored.
+An example:
+.IP
+.nf
+\f[C]
+#\ on\ this\ day,\ 6h\ was\ spent\ on\ client\ work,\ 1.5h\ on\ haskell\ FOSS\ work,\ etc.
+2016/2/1
+inc:client1\ \ \ ....\ ....\ ....\ ....\ ....\ ....
+fos:haskell\ \ \ ....\ ..\ 
+biz:research\ \ .
+
+2016/2/2
+inc:client1\ \ \ ....\ ....
+biz:research\ \ .
+\f[]
+.fi
+.PP
+Or with numbers:
+.IP
+.nf
+\f[C]
+2016/2/3
+inc:client1\ \ \ 4
+fos:hledger\ \ \ 3
+biz:research\ \ 1
+\f[]
+.fi
+.PP
+Reporting:
+.IP
+.nf
+\f[C]
+$\ hledger\ \-f\ t.timedot\ print\ date:2016/2/2
+2016/02/02\ *
+\ \ \ \ (inc:client1)\ \ \ \ \ \ \ \ \ \ 2.00
+
+2016/02/02\ *
+\ \ \ \ (biz:research)\ \ \ \ \ \ \ \ \ \ 0.25
+\f[]
+.fi
+.IP
+.nf
+\f[C]
+$\ hledger\ \-f\ t.timedot\ bal\ \-\-daily\ \-\-tree
+Balance\ changes\ in\ 2016/02/01\-2016/02/03:
+
+\ \ \ \ \ \ \ \ \ \ \ \ ||\ \ 2016/02/01d\ \ 2016/02/02d\ \ 2016/02/03d\ 
+============++========================================
+\ biz\ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 1.00\ 
+\ \ \ research\ ||\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 1.00\ 
+\ fos\ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 1.50\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ 3.00\ 
+\ \ \ haskell\ \ ||\ \ \ \ \ \ \ \ \ 1.50\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ 0\ 
+\ \ \ hledger\ \ ||\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ 3.00\ 
+\ inc\ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 6.00\ \ \ \ \ \ \ \ \ 2.00\ \ \ \ \ \ \ \ \ 4.00\ 
+\ \ \ client1\ \ ||\ \ \ \ \ \ \ \ \ 6.00\ \ \ \ \ \ \ \ \ 2.00\ \ \ \ \ \ \ \ \ 4.00\ 
+\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 7.75\ \ \ \ \ \ \ \ \ 2.25\ \ \ \ \ \ \ \ \ 8.00\ 
+\f[]
+.fi
+.PP
+I prefer to use period for separating account components.
+We can make this work with an account alias:
+.IP
+.nf
+\f[C]
+2016/2/4
+fos.hledger.timedot\ \ 4
+fos.ledger\ \ \ \ \ \ \ \ \ \ \ ..
+\f[]
+.fi
+.IP
+.nf
+\f[C]
+$\ hledger\ \-f\ t.timedot\ \-\-alias\ /\\\\./=:\ bal\ date:2016/2/4
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.50\ \ fos
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.00\ \ \ \ hledger:timedot
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0.50\ \ \ \ ledger
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.50
+\f[]
+.fi
+.PP
+default year directives may be used.
+.PP
+Here is a sample.timedot.
+
+
+.SH "REPORTING BUGS"
+Report bugs at http://bugs.hledger.org.
+
+.SH AUTHORS
+Simon Michael <simon@joyful.com>
+
+.SH COPYRIGHT
+
+Copyright (C) 2007-2015 Simon Michael.
+.br
+Released under GNU GPLv3+.
+
+.SH SEE ALSO
+hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1)
+.br
+hledger_csv(5), hledger_journal(5), hledger_timelog(5)
+
+For more information, see http://hledger.org.