@@ 7,27 7,19 @@ Overview
Generates a PDF invoice from TimeWarrior logs.
+
Dependencies
------------
- [Basser Lout](http://savannah.nongnu.org/projects/lout).
- [Go](https://golang.org).
-Both dependencies are probably in your package manager. vim comes with a Lout syntax.
-
-This software does not require any non-core Go libraries to build, so there's
-no `go.mod` file.
-
-### Why not LaTeX?
+Both dependencies are probably in your package manager. vim comes with a
+Lout syntax.
-1. Lout is a more simple syntax. I can hack together Lout without being
- proficient in it, and I have no need to be proficient in LaTeX outside of
- this project.
-2. Lout is a single 727kb executable. LaTeX (tetex-live) is 445MB distributed
- as a bunch of packages (on Arch), and that's considered a small
- implementation of LaTex. I've seen LaTeX installations consuming gigabytes
- of data.
-3. [More information about Lout](https://en.wikipedia.org/wiki/Lout_(software)).
+This software does not require any non-core Go libraries to build, so
+there's no `go.mod` file.
+
Installation
------------
@@ 41,41 33,21 @@ Copy `invoice` and `inv` to your extensi
chmod u+x inv
cp invoice inv ~/.timewarrior/extensions
+
Usage
-----
-In the normal course of things, you'd run this with `timew`, e.g.
-
- timew report inv 2019-12-01 - 2019-12-31 client:megacorp
-
-This runs the script, which also executes Lout to generate the PDF, and clean up. You can get the raw Lout source by using the `inventory` report:
-
- timew report inventory 2019-12-01 - 2019-12-31 client:megacorp
-
-The invoice command itself reads from STDIN and expects output in the format of `timew report`.
-
- invoice [args]
+Configure it first. It needs to know your information, your client's
+information, and other stuff, and it'll be unhappy if you don't
+configure it first.
-One way to do that is to have an `echo` report in the extensions directory:
-
- cat > ~/.timewarrior/extensions/echo <<EOL
- #!/bin/bash
-
- while read x; do
- echo $x
- done
- EOL
-
-and then:
-
- timew report echo 2019-12-01 - 2019-12-31 client:megacorp | ./invoice
### Configuration
-The template requires some configuration that uses TimeWarrior's configuration
-utility. Rates and addresses are pulled from the timew config, and this
-requires configuration before running the tool. Configurations can be set with
-the `timew config` command, e.g.
+The template requires some configuration that uses TimeWarrior's
+configuration utility. Rates and addresses are pulled from the
+timew config, and this requires configuration before running the
+tool. Configurations can be set with the `timew config` command, e.g.
timew config rate 60.0
@@ 137,30 109,115 @@ E.g.
You may enter as many clients as you wish.
-**Note**: TimeWarrior uses `#` as a comment character, and don't document how
-to escape it. I haven't yet figured it out, so you can't have it in any of the
-configuration fields.
+**Note**: TimeWarrior uses `#` as a comment character, and don't
+document how to escape it. I haven't yet figured it out, so you can't
+have it in any of the configuration fields.
-Next, you have to tag all of your records for that client with client:<client>,
-e.g.
+Next, you have to tag all of your records for that client with
+client:<client>, e.g.
timew tag @1 client:megacorp
-Run your reports with the `client:megacorp` tag; the program uses that to
-determine which client configuration information to use, which allows you to
-have multiple clients.
+Run your reports with the `client:megacorp` tag; the program uses that
+to determine which client configuration information to use, which allows
+you to have multiple clients.
+
+
+### Running
+
+In the normal course of things, you'd run this with `timew`, e.g.
+
+ timew report inv 2019-12-01 - 2019-12-31 client:megacorp
+
+The `inv` script does some set-up, calls `invoice` to generate the
+Lout source, runs `lout` to create the PDF, and then cleans up. It's
+a pretty simple script, and isn't necessary if you want to run some
+commands yourself.
+
Advanced
--------
-There is limited ability to override the template. To do so, have a file
-`invoice.tmpl` in the current directory. You can use the one in the source
-repository as a starting point. These are Go templates; Go replaces the stuff
-in double-braces (`{{` ... `}}`), and if you hard-code those you don't need the
-addresses in the configuration, or the client tags on your TimeWarrior records.
-You **do** still need the `rate` configuration, and the `{{range .}}` ...
-`{{end}}` markup. However, you can mess around with the table formats, fonts,
-and etcetera. Change the `$` to `€`. Move the columns around. Weighing in at
-78 lines long, it's not too complex. One thing to keep in mind:
-**double-braces are Go, single-braces are Lout.** Make sure there are spaces
-between Lout braces to prevent Go from trying to mess with them.
+### Raw Lout Source
+
+You can get the raw Lout source by using the `invoice` report:
+
+ timew report invoice 2019-12-01 - 2019-12-31 client:megacorp
+
+The invoice command itself reads from STDIN and expects output in the
+format of `timew report`.
+
+ invoice [args]
+
+One way to do that is to have an `echo` report in the extensions
+directory:
+
+ cat > ~/.timewarrior/extensions/echo <<EOL
+ #!/bin/bash
+
+ while read x; do
+ echo $x
+ done
+ EOL
+
+and then:
+
+ timew report echo 2019-12-01 - 2019-12-31 client:megacorp | ./invoice
+
+
+### Modify the report template
+
+There is limited ability to override the template. To do so, have a
+file `invoice.tmpl` in the current directory. You can use the one in
+the source repository as a starting point. These are Go templates;
+Go replaces the stuff in double-braces (`{{` ... `}}`), and if you
+hard-code those you don't need the addresses in the configuration,
+or the client tags on your TimeWarrior records. You **do** still
+need the `rate` configuration, and the `{{range .}}` ... `{{end}}`
+markup. However, you can mess around with the table formats, fonts,
+and etcetera. Change the `$` to `€`. Move the columns around. Weighing
+in at 78 lines long, it's not too complex. One thing to keep in mind:
+**double-braces are Go, single-braces are Lout.** Make sure there are
+spaces between Lout braces to prevent Go from trying to mess with them.
+
+**IMPORTANT**: Any time you change invoice.tmpl, you *must* run `go
+generate` before compiling the tool. This requires the bundling tool
+[esc](https://github.com/mjibson/esc), which you can get with `go get
+github.com/mjibson/esc`.
+
+
+Q & A
+-----
+
+Why not LaTeX?
+
+: Lout is a more simple syntax, with a much smaller learning curve. I
+ can (and do) go for years between using Lout and it's easy to pick up
+ each time; I can't say the same for TeX.
+
+ Lout is a single 727KB executable. LaTeX (tetex-live) is 445*MB*,
+ distributed as a bunch of packages (on Arch), and that's considered
+ a *small* implementation of LaTex. As I use these infrequently, I'd
+ rather clutter up my hard drive with a smaller tool.
+
+Why not Markdown?
+
+: It's not the right tool. An invoice is tabular data on (usually)
+ letterhead; Markdown has never claimed to be, and is not particularly
+ good at, desktop publishing, and it discourages tabular data. The
+ original Markdown format required escaping into HTML to do tables.
+
+Why not *X*?
+
+: I don't know *X*. I'm sure it's great, and I'd be thrilled if any
+ part of this project helps you implement a solution based around *X*.
+ If you do, please do let me know; I'd love to hear about it.
+
+Lout sounds awesome! Where can I learn more?
+
+: [Right here](https://en.wikipedia.org/wiki/Lout_(software)).
+
+Why `esc`, and not *Y*?
+
+: It was installed from an earlier project, and I haven't yet taken the
+ time to see if any of the other asset bundling tools are any better.