On 14 May 2008, at 18:31, Joshua D. Drake wrote:
On Wed, 14 May 2008 16:18:30 +0100 Stroller <..hidden..> wrote:If anyone wants a copy of my invoice.tex - the one used for generating the linked invoice - then I'll be glad to supply it, but there has been little interest in my "innovations" in the past.If you could write up a mini-howto on exactly what to change in your invoice.tex to allow people to use it for their own (like change thisline to say "x" for your company name) I would be happy to get it up onthe main website under a contributor section.
Hi Joshua, Jeff, Richard,Thanks for your interest, and my apologies for not replying sooner. I'd be glad for this template .tex file to be posted on the website or wherever.
The aim of my design was to harmonise with my company brand - which aims to present the customer with a modern, friendly and "approachable" look - whilst being as readable as possible. IIRC the default invoice.tex in SQL-Ledger was extremely bland - basically it was all Times Roman and looked like it was typed on MS Works Word- Processor for Windows 3.1, in an extremely simple layout. Sure, I wanted a "simple" look if that's a synonym for "minimalist" or "clean", but not if it's a synonym for "primitive" - besides, I detest Times Roman in any context outside of novels and newspapers. I mentioned that readability was a criteria, and I fear I may have compromised that by use of the handwriting font - although I'm pretty sure I tried all of them, and that's the clearest of the lot - but I really wanted to present my customers with the idea that they're dealing with a tradesman (ok, a _trendy_ tradesman) and the I think handwriting style does that.
As you can see from the sample invoice [1] most of my business is as a jobbing tradesman, charged at my hourly rate, so I kinda feel like the handwriting font for %itemnotes does conjure the idea of a plumber who has pulled the invoice off the dot-matrix (that his accountant demands that he maintains) and written in biro ink to explain each item charge. In fact, I did consider using a dot-matrix font, but I guess I like Verdana a _lot_ (I think I decided that dot- matrix is, in these days of laser printers, too contrived a style) and the LaTeX sans-serif Arev is virtually indistinguishable from Verdana. I think they're both clones of another, earlier and famous, Swiss font which has been around for a few decades (Gill?), but I feel that Arev's line-spacing (when I've tried it as a .ttf font on my Mac) is too tight - I do like "air" and "space" in design, I guess, and I haven't found a sans-serif aside from Verdana that gets that (IMO) right. Anyway, that may account for some "odd" LaTeX markup you may find in this template. I found trying to convert a truetype font to LaTeX to be both painful and a dead-loss (in its results), and there's really no point when there's a font as good as Arev so freely available; sorry if I could have written the line- respacing better and please email me if you have details of how to do so. It's also worth noting that Arev offers some alternate character forms suitable for email use - if you have a 1 or an l in your email address then there are individual character glyphs you can specify that (for example) curls the tail of the "l" slightly so that you can distinguish it as a lower-case "L" rather than a capital I or a numeral 1.
I chose the landscape print layout mostly because a supplier of mine also uses it, and I was just really taken with the style when I received their first invoice. And it's immediately obvious that the width provides more space for my verbose %itemnotes comments! When posting this invoice you fold it back on itself 2/3 of the way across the page (a vertical fold approximately halfway through the "payable" of "make payable to") so that the remaining left-hand side is the same width as a standard folded-A4 envelope. You then fold the invoice in half in the other direction, and the "Invoice to:" address will be locate correctly to appear in the window of a standard windowed envelope. It took a fair bit of fiddling of this template to get the address to sit in the window correctly, so again apologies if the LaTeX markup is a bit wonky - I would imagine that porting this template to US Letter paper sizes might be a bit of a chore.
I find reading this invoice.tex file to be fairly self-explanatory, but then maybe I'm overlooking any hard bits, and maybe the "easy bits" are only so because I spent SO much time on this project when I wrote it originally. ;)
Anyway you should find it easy to adapt this this to your own company:- company name is mentioned in line 43, VAT status (the next few lines deal with printing this centrally at the bottom of the page, or printing it alongside a page number, depending upon whether the latter is necessary)
- company name is mentioned again on line 71. - change address & contact details in lines 72 - 75. - "please make cheques payable to", line 113.- lines 120 - 121 - it's not uncommon in the UK to give one's bank details to allow payment via direct bank transfer in this way. Customers can use their bank's online facilities to make payment. You might alternatively use this whole minipage section for something else - terms & conditions, or whatever (see the next-but-one paragraph).
The original SQL-Ledger invoice.tex I worked from had a separate "letterhead" file that it imported from and which contained all the company details stuff. In many ways this is a great way of unifying the company name & VAT number across all the printed documents produced by your Ledger system, but I had to abandon that approach completely in order to get the look & feel I was looking for. I don't use any of the other printed documents offered by LedgerSMB, so this isn't a problem for me - I suppose that if one were to have multiple documents containing the company name one would simply create a "\newcommand\CompanyName{Pete The Plumber}" macro (see, for example, lines 37, 39 & 44), and place this definition in a "letterhead" file which which doesn't actually print anything but which is imported into all the other document templates. Then you could scatter \CompanyName and \VATnumber throughout your documents without having to worry when you rename your business to "Pete's Pools". This'd be a much better method than SQL-Ledger's old letterhead, which required you to keep at the top of all documents any information you wanted to share in common to all of them.
Where I've said "\end{itemize} \end{minipage}" (lines 125, 126), I don't think the stuff in brackets is necessary - although I won't swear to this, I think I put the "{itemize}" & "{minipage}" on those lines in only to improve legibility; I think the "{itemize}" & "{minipage}" on those lines are effectively only code comments. I think that only the "\end" parts are necessary, but don't change this - it is quite clear that the "\end{minipage}" on line 126 corresponds to the "\begin{minipage}" on line 109, so you can edit anything in between to your heart's content. The \vfill fills empty space with whitespace and in this instance ensures that text above it is pushed to the top of the minipage. This is a great example of how we're abusing the markup to do stuff for which LaTeX wasn't really intended - without it, the contents are centred vertically in the invisible minipage box, so that the "Payment:" line sits lower than the "Invoice to:" line. Yet the "Invoice to:" side (the "Invoice to:" minipage) does not need this - this makes no sense in the context of building an invoice, but it's perhaps (??) entirely logical in LaTeX's evolution for writing scientific textbooks and for journals. I find LaTeX full of whacky stuff like this that doesn't really make sense to me - if you're experienced with LaTeX you might find my markup to be really bad, but I find LaTeX often to be quite inscrutable and I can only arrive at the appearance I desire through some trial and error. I am frequently amazed by the insight to this language displayed by posters to the comp.text.tex newsgroup, and I would love to spend more time with LaTeX myself, really getting to the bottom of the language. I think that one might learn a much better grasp of the basics if one were to use it for that which which is was originally intended, laying out a book or a technical manuscript. I would _love_ to work from bare beginnings, laying out Pete's Guide to Portable Plumbing in the style of Knuth and that of the Journal of American Medicine and then do all the work to format it completely differently for a different audience, using LaTeX (or maybe just TeX??) correctly; I suspect the finished manual (if done correctly) would change little throughout the iterations, that "\usepackage" declarations would be minimised and be replaced with a single "\documentclass{plumbingmanual}" or "\pagestyle{manual}" entity.
I think this thread started because someone was having problems with word-wrapping their %itemnotes entries - see the longtable beginning line 135 (I think the "p" and "@" characters are relevant; see also [7]). If having problems with your LaTeX then delete everything that's not relevant to the problem in hand, try reprinting the invoice and only working on the problematic section. Take LOTS of backups of your work-in-progress. Only when you understand exactly what's going on - it might be a single character, or you might need to add a couple of columns to a table and then merge them in most rows - recombine your corrections with the rest of the document.
This longtable is, of course, the essential of the invoice. IIRC this was done *quite* differently in the default SQL-Ledger invoice.tex when I first started working from it - I think that that template used the core table to do *page* headers & footers and much else too. I basically ended up starting again from scratch and chose to use "\lfoot{} \cfoot{\VAT} \rfoot{}" (lines 50, 51) for page headers & footers (I think this is more "LaTeXy"). If making significant changes to Ledger templates be careful not to get caught out neglecting to handle how second & subsequent pages should be treated differently from the first. Anyway, in my version the table only does the what I consider to be the "invoice core" - I have a table header which displays the words "Part", "Description", "Quantity & Price", then the footer ("Total = £53.60"), then the table row for each individual part. You'll be able to match up the "\hline" and "\hhline" line declarations to the horizontal lines you see in the output. Defining the footer before the rows which are printed ahead of it is quite LaTeXy - I believe it's so that the parser knows before it gets to the bottom of the table how much room it needs for the footer, so can make any necessary page-breaks in good time.
The actual iteration - which shows a line for EACH item on the bill - is not done by LaTeX but by LedgerSMB (see "<?lsmb foreach number ? >", line 145) instead, but that doesn't stop you mixing any LaTeX commands you need. In my layout I use this latter feature in a way that may make the output somewhat unusual (??) - I don't see the point of saying "Orange £0.50p x1 £0.50p" when I can just say "Orange £0.50p" instead. Of course, one needs the per-item price and quantity fields when one is dealing with multiple and part quantities, so here I use the "ifthen" package (lines 154 - 156) to do so. I'm not a terribly experienced programmer, but I did Pascal in school and I hack around in Bash and (very occasionally) C; an if-then-else statement in any of those languages would seem to be easier to read than it is in LaTeX [5]. I also try throughout this template to cope with problems if you're including an item at zero charge - some releases of LedgerSMB throw an "NaN" error if an item is priced at 0.00, so I try to print "free gift!" instead. I would imagine that many accounts departments would prefer the quantity and per-item price stated explicitly even for a single orange, so I'd guess that the majority of sites will surely need to modify this template before use, and hack out my personal quirks. You should find the code a bit more readable when you've done so.
Not terribly important to mention (but I'll do so for the sake of completion) is the use of "ifpdf" - usually when printing paper copies in LedgerSMB, output is in PostScript (which is presumably piped straight to `lpr`); PDF format is used when emailing. Thus I use ifpdf to distinguish between invoices printed on my black & white LaserJet (the copy I retain) and the copy emailed in colour to the customer. Obviously there should be no significant changes in the invoice between the two copies, but I use it to force a different shade of greyscale than my laser printer would use if it converted the blue text on its own. I have in the past experimented with an outline black-and-white-only version of my logo which comes out of my laserprinter better than its muddy conversion of my colour logo to grayscale; I believe that problems with that may have been related to my distro's previous LaTeX package, before TeX Live was available, but haven't tried again lately.
WITH ONE EXCEPTION, all the packages and fonts used by this .tex file are provided by the 2007 version of the TeX Live distribution. I believe this should be pretty much "the standard" LaTeX package installed by most Linux distros - on Gentoo you simply `emerge app- text/texlive`, I guess on other (binary) distros you might have to go through your package manager ticking anything with "texlive" in the name. The one exception is the handwriting font [2] used for the % itemnotes comments, which is part of the Emerald Fonts package [3] and - on my installation at least - installation is non-obvious, certainly to a LaTeX n00b. Check to see if your package manager offers emerald-fonts (nothing to do with the X11 window manager) but you may have to install them manually instead (I have an ugly but working ebuild for Gentoo). I think that if you run this invoice.tex without the emerald fonts you get an error message - you might hack around this by commenting out lines 36 - 40 (&/or removing the "{\note ... }" from line 152), but whether this results in blank or Times Roman %itemnotes fields, the emerald fonts are worth having so that Knuth can whip up a quick menu in "Intimacy" italics [4] for his mate's restaurant, next time he's hanging at your place and in need of borrowing a LaTeX system. The pleasure of seeing my own invoice.tex in its full glory surely pales in comparison to the pleasure to be had at one-upping Knuth at LaTeX. I also like the slightly-grunge typewriter font, Pookie - generally the Emerald fonts are quite different from all the others supplied on a typical LaTeX system, and are quite interesting from that point of view.
I'm sorry to have rambled on so long, but I didn't want to simply provide you with the invoice.tex (which you copy to /usr/local/ ledgersmb/templates/$user/invoice.tex, of course) and leave you scratching your head when it errors out. Changing the company name is easy, but I found all the other work I had to do to achieve the look & feel I wanted to be quite a chore, and dealing with LaTeX to generally be quite the learning experience. I feel that I could easily cover several pages of wiki on this subject, so sorry I've ended up stuffing all my thoughts into a single obscenely-long email. If you're testing this for your own use then I suggest a LedgerSMB installation with a number of invoices in the system, and printing out a decent number of them; you may wish different behaviour than that I've chosen for two- and three-page invoices.
I think that the majority of people will fall into two camps as far as invoice customisation is concerned: those who use the default LedgerSMB templates with no changes at all (or perhaps just a change of font, nothing else), and those who who need to make lots of changes to it (or to do something very specifically different). For small companies - mom & pop businesses and those who don't consider all their stationary to be an important part of their "brand" - there's surely nothing wrong with the default template. I'm sure that there are many more people who will be quite happy with a single font change, but if you're pitching LedgerSMB to a client beware of the temptation to say "oh, yeah, we can customise the look of the documents all you want." I think one could easily spend many hours getting one's LedgerSMB invoices to exactly match the corporate stationery and whilst I'd LOVE to undertake this sort of stuff as paying jobs I won't be giving any discounts, so you could find yourself spending £100s or even £1000s if your graphics designers are fussy enough (or wasting an equivalent amount of your own time on the job if you're doing it "on a promise" to the customer).
If you're a "second category" person and need any real customisation to your invoice (and you're not paying me to do it for you ;) then I can't emphasise enough the value of the the comp.text.tex newsgroup [6] and of doing a "minimal example". If you're stuck then remove everything else from your work-in-progress except for the current problem, and print only that through LedgerSMB. Make a foo.tex in your home directory and create a similar layout by hand - it's probably best if you don't paste from the version that's giving you problems, but start again from scratch. Layout a similar table (or whatever) from first principles - when you've got "Oranges, Apples, Pears, Plums" displaying correctly when you're running `rubber foo.tex` by hand, you'll probably see the problem straight away. LaTeX does seem to be well-documented, which is obviously a good thing, but searching the 'net for help can lead you sites for rubber fetishists, which is distracting when you're trying to get the job done. Each LaTeX package on your system has a CTAN usage document, kinda the equivalent to a manpage, and you should be able to find these installed on your system (Gentoo users may need to set USE="doc"); for every "\usepackage{whatever}" entry I've made on lines 7 - 23 of my invoice.tex you should have a whatever.pdf describing the syntax of that package - see the ifthen [5] and longtable [7] ones for examples. If you can't find these then it may possibly be that your distro has supplied them only as .dvi files, which you have to convert to pdf for yourself using `dvipdf`. These usage documents are variable in quality, but they can be particularly handy when they give an obscure example which isn't covered in any of the beginners guides to LaTeX. There are LOADS of good books on LaTeX - it's a fantastic language from that point of view; there are a number of beginners guides that you can download in PDF format, and I can't think of one of them that I haven't found to be pretty good. Unlike some languages, the LaTeX subject space doesn't seem overwhelmed with people writing crap manuals - take a look at these links and save the lot to a folder on your desktop <http:// www.macrotex.net/texbooks/>, <http://www.physics.indiana.edu/~reu/ Latex/texbooks.html>.
Stroller.I guess these sorts of things are always a work-in-progress, so I have included a "version number" as a comment towards the top of this invoice.tex. This is version 1.10.5 - each of the previous iterations has fixed some minor formatting error that I only discovered afer deployment, but I'm mostly happy with this version, and have issued hundreds of invoices using it.
RELEASE NOTES, BUGS & KNOWN ISSUES:- Stroller's Friendly Modern invoice layout template for Ledger-SMB, release 1.10.5.
- Tested on LedgerSMB to 1.2.8.- If the company name & contact name are too long, word-wrapping may result in the following address format:
Cyberdyne Systems Of America, Incorporated. FAO:
Miles Dyson
1 Unknown Court,
Sunnvale
&c.
Instead of
Cyberdyne Systems Of America, Incorporated. FAO: Miles
Dyson
1 Unknown Court, &c.This is a result of attempting to make the address fit a windowed envelope, and the use of the other half of the page, to the right of the address, for the payment details. This should probably be fixed so that long lines are truncated, instead of wrapped. - LaTeX geometry{a4paper,landscape} results in SNAFU if one attempts to network print via CUPS to Canon iP3000 printer hosted on an OS X Mac from a Linux-hosted system. Printers set up directly on the LedgerSMB host seem to work fine (eg: http://localhost:631 -> add printer -> socket://192.168.1.9 -> HP Jetdirect -> laserjet4000.ppd is no problem).
- Please report any other issues.
Attachment:
invoice.tex
Description: Binary data
[1] <http://linux.stroller.uk.eu.org/SQL-Ledger/invoice.jpg> - Please do not reproduce this graphic or post it to the LedgerSMB website. I'd be glad for someone else to post a "screenshot" showing the output of my invoice.tex using the sanitised "Pete The Plumber" brand, but I don't want my own logo or billing details getting wider distribution in this context. I don't have a test-bench LedgerSMB installation on which I can print a sanitised PDF sample invoice myself.
[2] http://www.tug.dk/FontCatalogue/augie/ [3] http://www.ctan.org/tex-archive/fonts/emerald/ [4] http://www.speakeasy.org/~ecf/alphabet.htm[5] http://www.ifi.uio.no/it/latex-links/ifthen.pdf - your distro should install a copy of this somewhere on your system.
[6] http://groups.google.com/group/comp.text.tex/[7] http://www.maths.nottingham.ac.uk/common/resources/latex/ longtable.pdf