balance --gain needs documentation

[simonmichael]

trafficstars

balance --gain's functionality needs to be described in detail.

Related: https://www.reddit.com/r/plaintextaccounting/comments/141fyoq/hledger_investment_gain_calculation_problem suggests it sometimes shows realised gain, not just unrealised gain.

Some examples based on the above:

decimal-mark ,
commodity       1.000, TRY
commodity EUPWR 1.000,00

2023-04-12 * Buy stock
    Assets:Bank                                -1015 TRY  
    Assets:Investment:Stock:EUPWR                 25 EUPWR @ 40,6 TRY  

; with just the above:
;
; $ hledger bal --gain EUPWR
;          EUPWR 25,00
;         -1.015,0 TRY  Assets:Investment:Stock:EUPWR
; --------------------
;          EUPWR 25,00
;         -1.015,0 TRY  

; with an inferred market price:

; $ hledger bal --gain EUPWR --infer-market-prices
; --------------------
;                    0

; with a declared market price:

P    2023-05-30    EUPWR    94,65 TRY

; $ hledger bal --gain EUPWR
;          1.351,2 TRY  Assets:Investment:Stock:EUPWR
; --------------------
;          1.351,2 TRY  

; with the stock partly sold:

2023-05-11 * Sell part of stock
    Assets:Bank                                 603,72 TRY  
    Assets:Investment:Stock:EUPWR                -10 EUPWR @ 60,3728 TRY  

; $ hledger bal --gain EUPWR 
;       1.008,4780 TRY  Assets:Investment:Stock:EUPWR
; --------------------
;       1.008,4780 TRY  

; with the stock fully sold:

2023-05-12 * Sell rest of stock
    Assets:Bank                                 905,59 TRY
    Assets:Investment:Stock:EUPWR                -15 EUPWR @ 60,3728 TRY  = 0 TRY

; $ hledger bal --gain EUPWR
;         494,3200 TRY  Assets:Investment:Stock:EUPWR
; --------------------
;         494,3200 TRY