From 2dbe07a666d5b0801b55d8b37338ddd5cb1a09cb Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 21 Feb 2016 02:32:40 -0800 Subject: [PATCH] doc: mark up man pages for man/web rendering And commit the latest nroff output. It'll need retesting. --- hledger-api/hledger-api.1.md | 10 +++++++++ hledger-lib/hledger_csv.5 | 2 ++ hledger-lib/hledger_csv.5.md | 9 +++++++- hledger-lib/hledger_journal.5 | 11 ++++++++-- hledger-lib/hledger_journal.5.md | 7 +++++++ hledger-lib/hledger_timedot.5.md | 12 ++++++++--- hledger-lib/hledger_timelog.5.md | 7 +++++++ hledger-ui/hledger-ui.1 | 13 +++++++++--- hledger-ui/hledger-ui.1.md | 36 +++++++++++++++++++++++++++++--- hledger-web/hledger-web.1 | 2 ++ hledger-web/hledger-web.1.md | 10 +++++++++ hledger/hledger.1 | 7 +++++-- hledger/hledger.1.md | 11 ++++++++++ 13 files changed, 123 insertions(+), 14 deletions(-) diff --git a/hledger-api/hledger-api.1.md b/hledger-api/hledger-api.1.md index 1c9700728..14d636cf4 100644 --- a/hledger-api/hledger-api.1.md +++ b/hledger-api/hledger-api.1.md @@ -2,6 +2,8 @@ % % January 2016 +
+ # NAME hledger-api - web API server for the hledger accounting tool @@ -17,6 +19,11 @@ hledger is a cross-platform program for tracking money, time, or any other commo using double-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with ledger(1). +
+
+ +
+ hledger-api is a simple web API server, intended to support client-side web apps operating on hledger data. It comes with a series of simple client-side app examples, which drive it's evolution. @@ -101,6 +108,8 @@ access. +
+ # ENVIRONMENT **LEDGER_FILE** @@ -131,3 +140,4 @@ The need to precede options with `--` when invoked from hledger is awkward. +
diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index 6ab08e634..fe1193d96 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -8,6 +8,8 @@ hledger_csv \- reading CSV files with hledger, and the CSV rules file format .SH DESCRIPTION +.IP \[bu] 2 +toc .PP hledger can read CSV files, converting each CSV record into a journal entry (transaction), if you provide some conversion hints in a "rules diff --git a/hledger-lib/hledger_csv.5.md b/hledger-lib/hledger_csv.5.md index cba962178..6ffa283f8 100644 --- a/hledger-lib/hledger_csv.5.md +++ b/hledger-lib/hledger_csv.5.md @@ -1,13 +1,20 @@ % hledger_csv(5) -% +% % October 2015 +
+ # NAME hledger_csv - reading CSV files with hledger, and the CSV rules file format # DESCRIPTION +
+
+* toc +
+ hledger can read [CSV](http://en.wikipedia.org/wiki/Comma-separated_values) files, converting each CSV record into a journal entry (transaction), diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 66fa9a6e0..a1088a6b1 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -7,6 +7,8 @@ .PP hledger_journal \- reference for hledger\[aq]s journal file format .SH DESCRIPTION +.IP \[bu] 2 +toc .PP hledger\[aq]s usual data source is a plain text file containing journal entries in hledger journal format. @@ -698,11 +700,11 @@ $\ hledger\ print .PP You can specify a parent account which will be prepended to all accounts within a section of the journal. -Use the \f[C]account\f[] directive like so: +Use the \f[C]apply\ account\f[] directive like so: .IP .nf \f[C] -account\ home +apply\ account\ home 2010/1/1 \ \ \ \ food\ \ \ \ $10 @@ -712,6 +714,9 @@ end \f[] .fi .PP +(\f[C]!account\f[], \f[C]account\f[], and \f[C]end\ apply\ account\f[] +are also supported). +.PP If \f[C]end\f[] is omitted, the effect lasts to the end of the file. The above is equivalent to: .IP @@ -775,6 +780,8 @@ include\ path/to/file.journal If the path does not begin with a slash, it is relative to the current file. .PP +Glob patterns (\f[C]*\f[]) are not currently supported. +.PP The \f[C]include\f[] directive may only be used in journal files, and currently it may only include other journal files (eg, not CSV or timelog files.) diff --git a/hledger-lib/hledger_journal.5.md b/hledger-lib/hledger_journal.5.md index ade43e580..82d8c7d4e 100644 --- a/hledger-lib/hledger_journal.5.md +++ b/hledger-lib/hledger_journal.5.md @@ -2,12 +2,19 @@ % % October 2015 +
+ # NAME hledger_journal - reference for hledger's journal file format # DESCRIPTION +
+
+* toc +
+ hledger's usual data source is a plain text file containing journal entries in hledger journal format. This file represents a standard accounting [general journal](http://en.wikipedia.org/wiki/General_journal). I use file names ending in `.journal`, but that's not required. diff --git a/hledger-lib/hledger_timedot.5.md b/hledger-lib/hledger_timedot.5.md index 63f308c6b..611984440 100644 --- a/hledger-lib/hledger_timedot.5.md +++ b/hledger-lib/hledger_timedot.5.md @@ -2,12 +2,19 @@ % % February 2016 +
+ # NAME hledger_timedot - time logging format # DESCRIPTION +
+
+* toc +
+ 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. @@ -84,9 +91,8 @@ Balance changes in 2016/02/01-2016/02/03: || 7.75 2.25 8.00 ``` -I'd prefer to use period for separating account components. -We can rewrite these to the colon hledger requires with an -[account alias](#account-aliases): +I prefer to use period for separating account components. +We can make this work with an [account alias](#account-aliases): ```timedot 2016/2/4 diff --git a/hledger-lib/hledger_timelog.5.md b/hledger-lib/hledger_timelog.5.md index ce0903e83..182bee9ef 100644 --- a/hledger-lib/hledger_timelog.5.md +++ b/hledger-lib/hledger_timelog.5.md @@ -2,12 +2,19 @@ % % October 2015 +
+ # NAME hledger_timelog - hledger's timelog file format # DESCRIPTION +
+
+ +
+ hledger can read timelog files. [As with Ledger](http://ledger-cli.org/3.0/doc/ledger3.html#Time-Keeping), these are (a subset of) diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 7b7ca0ae6..2e69cce07 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -19,11 +19,18 @@ hledger is a cross\-platform program for tracking money, time, or any other commodity, using double\-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with ledger(1). +.IP \[bu] 2 +toc .PP hledger\-ui is hledger\[aq]s curses\-style interface. -It reads a hledger journal file (~/.hledger.journal, $LEDGER_FILE, or -\-f FILE) and provides a simple full\-screen console interface for -viewing account balances and transactions. +It reads a hledger journal file +.PP +(~/.hledger.journal, $LEDGER_FILE, or \-f FILE; see hledger(1) or +hledger_journal(5)) +.PP +and provides a simple full\-screen console interface for viewing account +balances and transactions. +.PP It is simpler and more convenient for browsing than the command\-line interface, but lighter and faster than hledger\-web. .PP diff --git a/hledger-ui/hledger-ui.1.md b/hledger-ui/hledger-ui.1.md index afdbe868f..751b92ebe 100644 --- a/hledger-ui/hledger-ui.1.md +++ b/hledger-ui/hledger-ui.1.md @@ -2,6 +2,8 @@ % % October 2015 +
+ # NAME hledger-ui - curses-style interface for the hledger accounting tool @@ -17,10 +19,34 @@ hledger is a cross-platform program for tracking money, time, or any other commo using double-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with ledger(1). +
+
+* toc + + + + + + + + + + + + +
+ hledger-ui is hledger's curses-style interface. -It reads a hledger journal file (~/.hledger.journal, $LEDGER_FILE, or -f FILE) and -provides a simple full-screen console interface for viewing account -balances and transactions. It is simpler and more convenient for +It reads a hledger journal file +
+(~/.hledger.journal, $LEDGER_FILE, or -f FILE; see hledger(1) or hledger_journal(5)) +
+and provides a simple full-screen console interface for viewing account balances and transactions. + +It is simpler and more convenient for browsing than the command-line interface, but lighter and faster than hledger-web. @@ -204,6 +230,8 @@ This screen will appear if there is a problem, such as a parse error, when you press g to reload. Once you have fixed the problem described, press g again to reload and restore normal operation. +
+ # ENVIRONMENT **LEDGER_FILE** @@ -233,3 +261,5 @@ visual indication that this is in progress. The register screen's switching between historic balance and running total based on query arguments may be confusing, and there is no column heading to indicate which is being displayed. + +
diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index 666235fc6..60ceba33a 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -19,6 +19,8 @@ hledger is a cross\-platform program for tracking money, time, or any other commodity, using double\-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with ledger(1). +.IP \[bu] 2 +toc .PP hledger\-web is hledger\[aq]s web interface. It starts a simple web application for browsing and adding transactions, diff --git a/hledger-web/hledger-web.1.md b/hledger-web/hledger-web.1.md index 1105a2ae4..ed50201e7 100644 --- a/hledger-web/hledger-web.1.md +++ b/hledger-web/hledger-web.1.md @@ -2,6 +2,8 @@ % % October 2015 +
+ # NAME hledger-web - web interface for the hledger accounting tool @@ -17,6 +19,11 @@ hledger is a cross-platform program for tracking money, time, or any other commo using double-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with ledger(1). +
+
+* toc +
+ hledger-web is hledger's web interface. It starts a simple web application for browsing and adding transactions, and optionally opens it in a web browser window if possible. @@ -137,6 +144,8 @@ The following common hledger options should also work: `-B --cost` : show amounts in their cost price's commodity +
+ # ENVIRONMENT **LEDGER_FILE** @@ -167,3 +176,4 @@ If you start two instances on the same port, the second one will appear to run normally, but you will be seeing pages served from the first one. +
diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 3a938fb9a..bec1a8f7c 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -22,6 +22,8 @@ It is inspired by and largely compatible with ledger(1). hledger aims to be a reliable, practical tool for daily use. This man page is a quick reference and introduction; for more complete docs, see http://hledger.org/manual. +.IP \[bu] 2 +toc .PP This is hledger's command\-line interface (there are also curses and web interfaces). @@ -35,8 +37,9 @@ user's $PATH and can invoke them as subcommands. .PP The journal file is \f[C]~/.hledger.journal\f[] by default, or another file path specified by \f[C]$LEDGER_FILE\f[]. -You can also specify a file with \f[C]\-f\ FILE\f[], or standard input -with \f[C]\-f\-\f[]. +(This should be a real environment variable, not a shell variable.) You +can also specify a file with \f[C]\-f\ FILE\f[], or standard input with +\f[C]\-f\-\f[]. .PP Transactions are dated movements of money between two (or more) named accounts, and are recorded with journal entries like this: diff --git a/hledger/hledger.1.md b/hledger/hledger.1.md index 2b406b43a..a6eed3e31 100644 --- a/hledger/hledger.1.md +++ b/hledger/hledger.1.md @@ -2,6 +2,8 @@ % % October 2015 +
+ # NAME hledger - a command-line accounting tool @@ -20,6 +22,11 @@ hledger aims to be a reliable, practical tool for daily use. This man page is a quick reference and introduction; for more complete docs, see http://hledger.org/manual. +
+
+* toc +
+ This is hledger’s command-line interface (there are also curses and web interfaces). Its basic function is to read a plain text file describing financial transactions (in accounting terms, a general journal) and @@ -484,6 +491,8 @@ $ hledger print desc:shop # show transactions with shop in the d $ hledger activity -W # show transaction counts per week as a bar chart ``` +
+ # ENVIRONMENT **LEDGER_FILE** @@ -510,3 +519,5 @@ Eg on POSIX, set LANG to something other than C. # REPORTING BUGS Report bugs at http://bugs.hledger.org. + +