diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 6cbd7e400..2e5c44f04 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,13 +1,8 @@ --- -title: hledger contributors' guide +title: hledger contributor guide --- -# Contributors' guide - -Quick links for everyone, plus a rough guide mostly for hledger -contributors and developers. - - +# Contributor guide ## Quick links diff --git a/MANUAL.md b/MANUAL.md index d58b2f308..48c59f599 100644 --- a/MANUAL.md +++ b/MANUAL.md @@ -451,13 +451,12 @@ read [timelog files](#timelog-reporting). hledger 0.18 can also read (the old `convert` command is no longer needed.) An arbitrary CSV file does not provide enough information to be parsed as -a journal. So when reading CSV, hledger first reads an additional file -called the [rules file](#the-rules-file), which identifies the CSV fields -and assigns accounts. For reading `FILE.csv`, hledger uses a rules file in -the same directory called `FILE.rules`, auto-creating it if needed. You -should configure the rules to best match your CSV file. You can specify a -different rules file with `--rules-file` (useful when reading from -standard input). +a journal. So when reading CSV, hledger looks for an additional +[rules file](#the-rules-file), which identifies the CSV fields and assigns +accounts. For reading `FILE.csv`, hledger uses `FILE.rules` in the same +directory, auto-creating it if needed. You should configure the rules file +to get the best data from your CSV file. You can specify a different rules +file with `--rules-file` (useful when reading from standard input). An example - sample.csv: @@ -648,10 +647,10 @@ Examples: #### test -This command runs hledger's internal self-tests and displays a quick -report. The -v option shows more detail, and a pattern can be provided to -filter tests by name. It's mainly used in development, but it's also nice -to be able to test for smoke at any time. +This command runs hledger's built-in unit tests and displays a quick +report. A pattern can be provided to filter tests by name. It's mainly +used in development, but it's also nice to be able to check hledger for +smoke at any time. Examples: @@ -754,12 +753,68 @@ Examples: The following extra commands will be available if they have been [installed](#installing) (run `hledger` by itself to find out): +#### web + +The web command (provided by the hledger-web package) runs a web +server providing a web-based user interface +([release demo](http://demo.hledger.org), +[latest demo](http://demo.hledger.org:5001)). The web UI provides +reporting, including a more useful account register view, and also data +entry and editing. + +web-specific options: + + --port=N serve on tcp port N (default 5000) + --base-url=URL use this base url (default http://localhost:PORT) + +If you want to visit the web UI from other machines, you'll need to use +this option to fix the hyperlinks. Just give your machine's host name or +ip address instead of localhost. This option is also lets you conform to a +custom url scheme when running hledger-web behind a reverse proxy as part +of a larger site. Note that the PORT in the base url need not be the same +as the `--port` argument. + +Warning: unlike other hledger commands, `web` can alter existing journal +data, via the edit form. A numbered backup of the file will be saved on +each edit, normally (ie if file permissions allow, disk is not full, etc.) +Also, there is no built-in access control. So unless you run it behind an +authenticating proxy, any visitor to your server will be able to see and +overwrite the journal file (and included files.) + +hledger-web disallows edits which would leave the journal file not in +valid [journal format](#the-journal-file). If the file becomes unparseable +by other means, hledger-web will show an error until the file has been +fixed. + +Examples: + + $ hledger-web + $ hledger-web -E -B --depth 2 -f some.journal + $ hledger-web --port 5010 --base-url http://some.vhost.com --debug + +#### vty + +The vty command (provided by the hledger-vty package) starts a simple +curses-style (full-screen, text) user interface, which allows interactive +navigation of the print/register/balance reports. This lets you browse +around and explore your numbers quickly with less typing. + +vty-specific options: + + --debug-vty run with no terminal output, showing console + +Examples: + + $ hledger vty + $ hledger vty -BE food + #### chart -The chart command saves an image file, by default "hledger.png", showing a -basic pie chart of your top account balances. Note that positive and -negative balances will not be displayed together in the same chart; any -balances not matching the sign of the first one will be ignored. +The chart command (provided by the hledger-chart package) saves an image +file, by default "hledger.png", showing a basic pie chart of your top +account balances. Note that positive and negative balances will not be +displayed together in the same chart; any balances not matching the sign +of the first one will be ignored. chart-specific options: @@ -788,61 +843,6 @@ Examples: $ hledger chart ^expenses -o balance.png --size 1000x600 --items 20 $ for m in 01 02 03 04 05 06 07 08 09 10 11 12; do hledger chart -p 2009/$m ^expenses --depth 2 -o expenses-2009$m.png --size 400x300; done -#### vty - -The vty command starts a simple curses-style (full-screen, text) user -interface, which allows interactive navigation of the -print/register/balance reports. This lets you browse around and explore -your numbers quickly with less typing. - -vty-specific options: - - --debug-vty run with no terminal output, showing console - -Examples: - - $ hledger vty - $ hledger vty -BE food - -#### web - -The web command (an add-on provided by the hledger-web package) runs a web -server providing a web-based user interface -([release demo](http://demo.hledger.org), -[latest demo](http://demo.hledger.org:5001)). The web UI provides -reporting, including a more useful account register view, and also data -entry and editing. - -web-specific options: - - --port=N serve on tcp port N (default 5000) - --base-url=URL use this base url (default http://localhost:PORT) - -If you want to visit the web UI from other machines, you'll need to use -this option to fix the hyperlinks. Just give your machine's host name or -ip address instead of localhost. This option is also lets you conform to a -custom url scheme when running hledger-web behind a reverse proxy as part -of a larger site. Note that the PORT in the base url need not be the same -as the `--port` argument. - -Warning: unlike other hledger commands, `web` can alter existing journal -data, via the edit form. A numbered backup of the file will be saved on -each edit, normally (ie if file permissions allow, disk is not full, etc.) -Also, there is no built-in access control. So unless you run it behind an -authenticating proxy, any visitor to your server will be able to see and -overwrite the journal file (and included files.) - -hledger-web disallows edits which would leave the journal file not in -valid [hledger format](#the-journal-file). If the journal file becomes -unparseable by other means, hledger-web will show an error until the file -has been fixed. - -Examples: - - $ hledger-web - $ hledger-web -E -B --depth 2 -f some.journal - $ hledger-web --port 5010 --base-url http://some.vhost.com --debug - ## Reporting options The following additional features and options allow for fine-grained diff --git a/NEWS.md b/NEWS.md index e11b4eff9..9012d248a 100644 --- a/NEWS.md +++ b/NEWS.md @@ -6,7 +6,7 @@ title: hledger news ## (unreleased) hledger 0.18 - * CSV is now treated as a native data format, and the convert command + * CSV is now handled as a native data format, and the convert command has been dropped. Instead of `hledger convert FILE.csv`, do `hledger -f FILE.csv print`. * the [`Hledger.Read` API](http://hledger.org/api/Hledger-Read.html) has diff --git a/README.md b/README.md index 172e1bde5..2659719d2 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ suited to techies. I use it every day to: - track invoices hledger is first a command-line tool, but also provides a web interface -(try the [demo](http://demo.hledger.org)). Read the [docs](MANUAL.html) to +(try the [demo](http://demo.hledger.org)). Read the [manual](MANUAL.html) to learn more, including [how we are different from ledger](FAQ.html#how-does-hledger-relate-to-ledger), and get started tracking your numbers! @@ -28,7 +28,7 @@ and get started tracking your numbers! Donate with WePay -For support and more technical info, see [development](DEVELOPMENT.html) +For support and more technical info, see the [contributor guide](DEVELOPMENT.html) or [email me](mailto:simon@joyful.com?subject=hledger:). I appreciate -feedback on and help with all aspects of hledger. Please give it a try and +feedback and help with all aspects of hledger. Please give it a try and let me know how we're doing. Best -Simon