doc: style devguide, howtos

doc/developer-guide.md

@@ -211,17 +211,21 @@ and the default view given by [bugs.hledger.org](http://bugs.hledger.org) exclud
    On some platforms the command will be eg `gmake` instead of `make`.
 4. Get the hledger repo:
 
-        git clone https://github.com/simonmichael/hledger.git
+    ```shell
+    $ git clone https://github.com/simonmichael/hledger.git
+    ```
 
 5. You might want to install or upgrade some of these haskell developer tools.
    If you're not sure, skip this step and return to it as needed.
    Be sure the cabal bin directory where these are installed (eg ~/.cabal/bin) is in your PATH.
 
-        cabal update
+    ```{.shell .bold}
-        cabal install alex happy       # if you get alex/happy-related errors when building hledger
+    $ cabal update
-        cabal install haddock          # needed to build hledger API docs
+    $ cabal install alex happy       # if you get alex/happy-related errors when building hledger
-        cabal install shelltestrunner  # needed to run hledger functional tests (may need latest git version)
+    $ cabal install haddock          # needed to build hledger API docs
-        cabal install hoogle hlint     # maybe useful for searching API docs and checking code
+    $ cabal install shelltestrunner  # needed to run hledger functional tests (may need latest git version)
+    $ cabal install hoogle hlint     # maybe useful for searching API docs and checking code
+    ```
 
     You'll also want a comfortable code editor, preferably with Haskell support.
     (I use emacs + [haskell-mode](https://github.com/haskell/haskell-mode),
@@ -229,10 +233,12 @@ and the default view given by [bugs.hledger.org](http://bugs.hledger.org) exclud
 
 6. Install haskell libs required by hledger:
 
-        cabal update
+    ```{.shell .bold}
-        cd hledger
+    $ cabal update
-        cabal sandbox init   # optional
+    $ cd hledger
-        make installdeps     # or cabal install --only-dep ./hledger-lib ./hledger [./hledger-web]
+    $ cabal sandbox init   # optional
+    $ make installdeps     # or cabal install --only-dep ./hledger-lib ./hledger [./hledger-web]
+    ```
 
     This will install the required dependencies from Hackage.
     If you're new to cabal, you can expect problems at this stage.
@@ -242,13 +248,17 @@ and the default view given by [bugs.hledger.org](http://bugs.hledger.org) exclud
 
 7. Build with cabal:
 
-        make cabalbuild
+    ```shell
+    $ make cabalbuild
+    ```
 
     (Tip: `make cabalCMD` runs `cabal CMD` in each of the hledger packages).
 
 8. Build with GHC:
 
-        make bin/hledgerdev
+    ```shell
+    $ make bin/hledgerdev
+    ```
 
     This builds hledger (and hledger-lib) with GHC directly, without using cabal,
     and as quickly as possible, without optimizations (the "dev" suffix is a reminder of this).

doc/site/css/style.css

@@ -29,7 +29,12 @@ pre {
 		border:thin solid #eec;
 		/* border:none; */
 }
-.csv, .rules {
+.csv {
+		background-color:#cce;
+		border:thin solid #aad;
+		/* border:none; */
+}
+.rules {
 		background-color:#eef;
 		border:thin solid #cce;
 		/* border:none; */

doc/site/how-to-read-csv-files.md

@@ -3,51 +3,55 @@
 Here's a quick example of [converting a CSV file](manual.html#csv).
 
 Say we have downloaded `checking.csv` from a bank for the first time:
-
+```csv
-    "Date","Note","Amount"
+"Date","Note","Amount"
-    "2012/3/22","DEPOSIT","50.00"
+"2012/3/22","DEPOSIT","50.00"
-    "2012/3/23","TRANSFER TO SAVINGS","-10.00"
+"2012/3/23","TRANSFER TO SAVINGS","-10.00"
+```
 
 We tell hledger how to intepret this with a file named `checking.csv.rules`, using the [CSV rules syntax](manual.html#csv). Eg:
+```rules
+# skip the first CSV line (headings)
+skip 1
 
-    # skip the first CSV line (headings)
+# use the first three fields in each CSV record as transaction date, description and amount respectively
-    skip 1
+fields   date, description, amount
 
-    # use the first three fields in each CSV record as transaction date, description and amount respectively
+# prepend $ to CSV amounts
-    fields   date, description, amount
+currency $
 
-    # prepend $ to CSV amounts
+# always set the first account to assets:bank:checking
-    currency $
+account1 assets:bank:checking
 
-    # always set the first account to assets:bank:checking
+# if the CSV record contains ‘SAVINGS’, set the second account to assets:bank:savings
-    account1 assets:bank:checking
+# (if not set, it will be expenses:unknown or income:unknown)
-
+if ~ SAVINGS
-    # if the CSV record contains ‘SAVINGS’, set the second account to assets:bank:savings
+  account2 assets:bank:savings
-    # (if not set, it will be expenses:unknown or income:unknown)
+```
-    if ~ SAVINGS
-      account2 assets:bank:savings
 
 Now hledger can read this CSV file as journal data:
 
-    $ hledger -f checking.csv print
+```shell
-    using conversion rules file checking.csv.rules
+$ hledger -f checking.csv print
-    2012/03/22 DEPOSIT
+using conversion rules file checking.csv.rules
-        income:unknown             $-50.00
+2012/03/22 DEPOSIT
-        assets:bank:checking        $50.00
+    income:unknown             $-50.00
+    assets:bank:checking        $50.00
 
-    2012/03/23 TRANSFER TO SAVINGS
+2012/03/23 TRANSFER TO SAVINGS
-        assets:bank:savings         $10.00
+    assets:bank:savings         $10.00
-        assets:bank:checking       $-10.00
+    assets:bank:checking       $-10.00
+```
 
 We might save this output as `checking.journal`, and/or merge it (manually) into the main journal file.
 We could also run other commands:
-
+```shell
-    $ hledger -f checking.csv balance
+$ hledger -f checking.csv balance
-    using conversion rules file checking.csv.rules
+using conversion rules file checking.csv.rules
-                  $50.00  assets:bank
+              $50.00  assets:bank
-                  $40.00    checking
+              $40.00    checking
-                  $10.00    savings
+              $10.00    savings
-                 $-50.00  income:unknown
+             $-50.00  income:unknown
-    --------------------
+--------------------
-                       0
+                   0
-
+```

doc/site/how-to-use-account-aliases.md

@@ -3,43 +3,47 @@
 Here's an example of using [account aliases](manual.html#account-aliases).
 
 Say a sole proprietor has a `personal.journal`:
-
+```journal
-    2014/1/2
+2014/1/2
-        expenses:food  $1
+    expenses:food  $1
-        assets:cash
+    assets:cash
+```
 
 and a `business.journal`:
-
+```journal
-    2014/1/1
+2014/1/1
-        expenses:office supplies  $1
+    expenses:office supplies  $1
-        assets:business checking
+    assets:business checking
+```
 
 So each entity (the business owner, and the business) has their own file with its own simple chart of accounts.
 However, at tax reporting time we need to view these as a single entity (at least in the US).
 In `unified.journal`, we include both files, and rewrite the personal
 account names to fit into the business chart of accounts,
+```journal
+alias expenses    = equity:draw:personal
+alias assets:cash = assets:personal cash
+include personal.journal
+end aliases
 
-    alias ^expenses    = equity:draw:personal
+include business.journal
-    alias ^assets:cash = assets:personal cash
+```
-    include personal.journal
-    end aliases
-
-    include business.journal
 
 Now we can see the data from both files at once, and the personal account names have changed:
+```shell
+$ hledger -f unified.journal print
+2014/01/01                                    # from business.journal - no aliases applied
+    expenses:office supplies            $1
+    assets:business checking           $-1
 
-    $ hledger -f unified.journal print
+2014/01/02                                    # from personal.journal
-    2014/01/01                                    # from business.journal - no aliases applied
+    equity:draw:personal:food            $1   # <- was expenses:food
-        expenses:office supplies            $1
+    assets:personal cash                $-1   # <- was assets:cash
-        assets:business checking           $-1
+```
-
-    2014/01/02                                    # from personal.journal
-        equity:draw:personal:food            $1   # <- was expenses:food
-        assets:personal cash                $-1   # <- was assets:cash
 
 You can also specify aliases on the command line. This could be useful to
 quickly rewrite account names when sharing a report with someone else, such as
 your accountant:
-
+```shell
-    $ hledger --alias 'my earning=income:business' ...
+$ hledger --alias 'my earning=income:business' ...
-
+```