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
-    # (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
+2012/03/22 DEPOSIT
     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: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
               $40.00    checking
               $10.00    savings
              $-50.00  income:unknown
-    --------------------
+--------------------
                    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
     assets:cash
+```
 
 and a `business.journal`:
-
+```journal
-    2014/1/1
+2014/1/1
     expenses:office supplies  $1
     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
+$ hledger -f unified.journal print
-    2014/01/01                                    # from business.journal - no aliases applied
+2014/01/01                                    # from business.journal - no aliases applied
     expenses:office supplies            $1
     assets:business checking           $-1
 
-    2014/01/02                                    # from personal.journal
+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' ...
-
+```