gnucash stable: Multiple changes pushed
Geert Janssens
gjanssens at code.gnucash.org
Thu May 23 09:11:30 EDT 2024
Updated via https://github.com/Gnucash/gnucash/commit/e8e179fd (commit)
via https://github.com/Gnucash/gnucash/commit/387b4988 (commit)
via https://github.com/Gnucash/gnucash/commit/c816d2b3 (commit)
via https://github.com/Gnucash/gnucash/commit/e8d72ad5 (commit)
via https://github.com/Gnucash/gnucash/commit/6cd8e4e4 (commit)
via https://github.com/Gnucash/gnucash/commit/d8ac86af (commit)
via https://github.com/Gnucash/gnucash/commit/cf7ff076 (commit)
via https://github.com/Gnucash/gnucash/commit/da12a212 (commit)
via https://github.com/Gnucash/gnucash/commit/891b921c (commit)
via https://github.com/Gnucash/gnucash/commit/00511295 (commit)
via https://github.com/Gnucash/gnucash/commit/39aa5f9c (commit)
via https://github.com/Gnucash/gnucash/commit/48b9fa80 (commit)
via https://github.com/Gnucash/gnucash/commit/58b4ee35 (commit)
via https://github.com/Gnucash/gnucash/commit/3c860737 (commit)
from https://github.com/Gnucash/gnucash/commit/038405b3 (commit)
commit e8e179fd8fb7a951037e7b825d6c18d091adcde3
Author: Geert Janssens <geert at kobaltwit.be>
Date: Thu May 23 15:03:50 2024 +0200
Drop remainder of files in libgnucash/doc
Relevant diagrams have been added in the wiki as png files.
The html files with financial calculations are copyrighted
by someone outside of the gnucash project. I'd rather not
add that info to the wiki. Similar information should be
easy to find on the internet.
diff --git a/libgnucash/CMakeLists.txt b/libgnucash/CMakeLists.txt
index a0ea47cf49..44dc1e5325 100644
--- a/libgnucash/CMakeLists.txt
+++ b/libgnucash/CMakeLists.txt
@@ -4,7 +4,6 @@
add_subdirectory (app-utils)
add_subdirectory (backend)
add_subdirectory (core-utils)
-add_subdirectory (doc)
add_subdirectory (engine)
add_subdirectory (gnc-module)
add_subdirectory (quotes)
diff --git a/libgnucash/doc/CMakeLists.txt b/libgnucash/doc/CMakeLists.txt
deleted file mode 100644
index f816f92d1b..0000000000
--- a/libgnucash/doc/CMakeLists.txt
+++ /dev/null
@@ -1,9 +0,0 @@
-set(doc_FILES
- constderv.html
- finderv.html
- finutil.html
- README
- )
-
-set_local_dist(doc_DIST_local CMakeLists.txt ${doc_FILES})
-set(doc_DIST ${doc_DIST_local} ${doc_design_DIST} PARENT_SCOPE)
diff --git a/libgnucash/doc/README b/libgnucash/doc/README
deleted file mode 100644
index ea663726e8..0000000000
--- a/libgnucash/doc/README
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-Please note that there is additional documentation in various
-source subdirectories: for example, src/engine/*.txt
diff --git a/libgnucash/doc/constderv.html b/libgnucash/doc/constderv.html
deleted file mode 100644
index 0dc58bbaa6..0000000000
--- a/libgnucash/doc/constderv.html
+++ /dev/null
@@ -1,93 +0,0 @@
-<HTML>
-<HEAD>
-
-<TITLE>Financial Equations Documentation</TITLE>
-</HEAD>
-<BODY>
-<A NAME="TOP"></A>
-<A HREF="./finutil.html#ConstOrigData">Return</A>
-<HR>
-<h1>Constant Repayment to Principal Equations Derivation</h1>
-<p>In this loan, each total payment is different, with each succeeding payment
-less than the preceding payment. Each payment is the total of the constant
-amount to the principal plus the interest for the period. The constant payment
-to the principal is computed as:
-
-<pre>
- C = -PV / N
-
-<p>Where PV is the loan amount to be repaid in N payments (periods). Thus the
-principal after the first payment is:
-
-<pre>
- PV[1] = PV[0] + C = PV + C
-</pre>
-
-<p>after the second payment, the principal is:
-
-<pre>
- PV[2] = PV[1] + C = PV[0] + 2C
-</pre>
-
-<p>In general, the remaining principal after n payments is:
-
-<pre>
- PV[n] = PV[0] + nC = PV + nC
-</pre>
-
-<p>If the effective interest per payment period is i, then the interest for the
-first payment is:
-
-<pre>
- I[1] = -i*PV[0]
-</pre>
-
-<p>and for the second:
-
-<pre>
- I[2] = -i * PV[1]
-</pre>
-
-<p>and in general, for the n'th payment the interest is:
-
-<pre>
- I[n] = -i * PV[n-1]
- = -i * (PV + (n - 1)C)
-</pre>
-
-<p>The total payment for any period, n, is:
-
-<pre>
- P[n] = C + I[n]
- = C - i * (PV + (n - 1)C)
- = C(1 + i) - i * (PV + nC)
-</pre>
-
-<p>The total interest paid to period n is:
-
-<pre>
- T[n] = I[1] + I[2] + I[3] + ... + I[n]
- T[n] = sum(j = 1 to n: I[j])
- T[n] = sum(j = 1 to n: -i * (PV + (j-1)C))
- T[n] = sum(j=1 to n: -i*PV) + sum(j=1 to n: iC) + sum(j=1 to n: -iCj)
- T[n] = -i*n*PV + i*n*C - i*C*sum(j=1 to n:j)
- sum(j=1 to n:j) = n(n+1)/2
- T[n] = -i*n*(PV + C) - i*C*n(n+1)/2
- T[n] = -i*n*(PV + (C*(n - 1)/2))
-</pre>
-
-<p>Note: substituting for C = -PV/N, in the equations for PV[n], I[n], P[n], and T[n]
-would give the following equations:
-
-<pre>
- PV[n] = PV*(1 - n/N)
- I[n] = -i*PV*(1 + N - n)/N
- P[n] = -i*PV*(2 + N - n)/N
- T[n] = -i*n*PV*(2*N - n + 1)/(2*N)
-</pre>
-
-<p>Using these equations for the calculations would eliminate the dependence
-on C, but only if C is always defined as above and would eliminate the
-possibility of another value for C. If the value of C was less than -PV/N
-then a balloon payment would be due at the final payment and this is a possible
-alternative for some people.
diff --git a/libgnucash/doc/dia/components.dia b/libgnucash/doc/dia/components.dia
deleted file mode 100644
index 6fec466415..0000000000
Binary files a/libgnucash/doc/dia/components.dia and /dev/null differ
diff --git a/libgnucash/doc/dia/structures-alt.dia b/libgnucash/doc/dia/structures-alt.dia
deleted file mode 100644
index 926ead4870..0000000000
Binary files a/libgnucash/doc/dia/structures-alt.dia and /dev/null differ
diff --git a/libgnucash/doc/dia/structures.dia b/libgnucash/doc/dia/structures.dia
deleted file mode 100644
index 26609e87d6..0000000000
Binary files a/libgnucash/doc/dia/structures.dia and /dev/null differ
diff --git a/libgnucash/doc/finderv.html b/libgnucash/doc/finderv.html
deleted file mode 100644
index f370d15eb2..0000000000
--- a/libgnucash/doc/finderv.html
+++ /dev/null
@@ -1,337 +0,0 @@
-<HTML>
-<HEAD>
-
-<TITLE>Financial Equations Documentation</TITLE>
-</HEAD>
-<BODY>
-<A NAME="TOP"></A>
-<A HREF="./finutil.html#FinEquation">Return</A>
-<HR>
-<br>
-<dl>
-<dt><A HREF="#BasicEquation">Basic Equation</A></dt>
-<dt><A HREF="#SeriesSum">Series Sum</A></dt>
-</dl>
-<HR>
-<h1>Financial Equation Derivation</h1>
-<p>The financial equation is derived in the following manner:
-
-<p>Start with the basic equation to find the balance or Present Value, PV[1], after
-one payment period. Note PV[1] is the Present Value after one payment and PV[0]
-is the initial Present Value. PV[0] will be shortened to just PV.
-
-<p>The interest due at the end of the first payment period is the original present value,
-PV, times the interest rate for the payment period plus the periodic payment times the
-interest rate for beginning of period payments:
-
-<p>ID[1] = PV * i + X * PMT * i = (PV + X * PMT) * i
-
-<p>The Present Value after one payment is the original Present Value with the periodic
-payment, PMT, and interest due, ID[1], added:
-
-<pre>
- PV[1] = PV + (PMT + ID[1])
- PV[1] = PV + (PMT + (PV + X * PMT) * i)
- PV[1] = PV * (1 + i) + PMT * (1 + Xi)
-</pre>
-
-<p>This equation works for all of the cash flow diagrams shown previously. The Present Value,
-money received or paid, is modified by a payment made at the beginning of a payment
-period and multiplied by the effective interest rate to compute the interest
-due during the payment period. The interest due is then added to the payment
-to obtain the amount to be added to the Present Value to compute the new Present Value.
-
-<p>For diagram 1): PV < 0, PMT == 0, PV[1] < 0
-<br>For diagram 2): PV == 0, PMT < 0, PV[1] < 0
-<br>For Diagram 3): PV > 0, PMT < 0, PV[1] >= 0 or PV[1] <= 0
-<br>For Diagram 4): PV < 0, PMT > 0, PV[1] <= 0 or PV[1] >= 0
-
-<p>X may be 0 or 1 for any diagram.
-
-<p>For the standard loan, PV is the money borrowed, PMT is the periodic payment to repay
-the loan, i is the effective interest rate agreed upon and FV is the residual loan amount
-after the agreed upon number of periodic payment periods. If the loan is fully paid off
-by the periodic payments, FV is zero, 0. If the loan is not completely paid off after the
-agreed upon number of payments, a balloon payment is necessary to completely pay off the loan.
-FV is then the amount of the needed balloon payment. For a loan in which the borrower pays
-only enough to repay the interest due during a payment period, interest only loan, the
-balloon payment is equal to the negative of PV.
-
-<p>To calculate the Present Value after the second payment period, the above calculation
-is applied iteratively to PV[1] to obtain PV[2]. In fact to calculate the Present Value
-after any payment period, PV[n], the above equation is applied iteratively to PV[n-1]
-as shown below.
-
-<pre>
- PV[2] = PV[1] + (PMT + (PV[1] + X * PMT) * i)
- = PV[1] * (1 + i) + PMT * (1 + iX)
- = (PV * (1 + i) + PMT * (1 + iX)) * (1 + i) + PMT * (1 + iX)
- = PV * (1 + i)^2 + PMT * (1 + iX) * (1 + i)
- + PMT * (1 + iX)
-</pre>
-
-<p>Similarly, PV[3] is computed from PV[2] as:
-
-<pre>
- PV[3] = PV[2] + (PMT + (PV[2] + X * PMT) * i)
- = PV[2] * (1 + i) + PMT * (1 + iX)
- = (PV * (1 + i)^2 + PMT * (1 + iX) * (1 + i)
- + PMT * (1+ iX)) * (1 + i)
- + PMT * (1+ iX)
- = PV * (1 + i)^3 + PMT * (1 + iX) * (1 + i)^2
- + PMT * (1 + iX) * (1 + i)
- + PMT * (1 + iX)
-</pre>
-
-<p>And for the n'th payment, PV[n] is computed from PV[n-1] as:
-
-<pre>
- PV[n] = PV[n-1] + (PMT + (PV[n-1] + X * PMT) * i)
- PV[n] = PV * (1 + i)^n + PMT * (1 + iX) * (1 + i)^(n-1)
- + PMT * (1 + iX) * (1 + i)^(n-2) +
- .
- .
- .
- + PMT * (1 + iX) * (1 + i)
- + PMT * (1 + iX)
- PV[n] = PV * (1 + i)^n + PMT * (1 + iX) * [(1 + i)^(n-1) + ... + (1 + i) + 1]
-</pre>
-
-<p>The formula for PV[n] can be proven using mathematical induction.
-
-<A NAME="BasicEquation">
-<h1>Basic Financial Equation</h1></A>
-<p>As shown above, the basic financial transaction equation is simply:
-
-<pre>
- PV[n] = PV[n-1] + (PMT + (PV[n-1] + X * PMT) * i)
- = PV[n-1] * (1 + i) + PMT * (1 + iX)
- for: n >= 1
-</pre>
-
-<p>relating the Present Value after n payments, PV[n] to the previous Present Value, PV[n-1].
-
-<!--########################################################################-->
-
-<hr>
-<A NAME="SeriesSum">
-<h1>Series Sum</h1></A>
-<p>The sum of the finite series:
-
-<p>1 + k + (k^2) + (k^3) + ... + (k^n) = (1-k^(n+1))/(1-k)
-
-<p>as can be seen by the following. Let S(n) be the series sum. Then
-
-<p>S(n) - k * S(n) = 1 - k^(n+1)
-
-<p>and solving for S(n):
-
-<p>S(n) = (1-k^(n+1))/(1-k) = 1 + k + (k^2) + (k^3) + ... + (k^n)
-
-<!--########################################################################-->
-<hr>
-
-<p>Using this in the equation above for PV[n], we have:
-
-<pre>
- PV[n] = PV * (1 + i)^n + PMT * (1 + iX) * [(1 + i)^(n-1) + ... + (1 + i) + 1]
- = PV * (1 + i)^n + PMT * (1 + iX) * [1 - (1 + i)^n]/[1 - (1 + i)]
- = PV * (1 + i)^n + PMT * (1 + iX) * [1 - (1 + i)^n]/[-i]
- = PV * (1 + i)^n + PMT * (1 + iX) * [(1 + i)^n - 1]/i
-</pre>
-
-<p>or:
-
-<pre>
- PV * (1 + i)^n + PMT * [(1 + i)^n - 1]/i - PV[n] = 0
-</pre>
-
-<p>If after n payments, the remaining balance is repaid as a lump sum, the lump sum
-is known as the Future Value, FV[n]. Since FV[n] is negative if paid and positive
-if received, FV[n] is the negative of PV[n].
-
-<p>Setting: FV[n] = -PV[n]
-
-<p>Since n is assumed to be the last payment, FV[n] will be shortened to simply
-FV for the last payment period.
-
-<pre>
- PV*(1 + i)^n + PMT*(1 + iX)*[(1 + i)^n - 1]/i + FV = 0
-</pre>
-
-<p>Up to this point, we have said nothing about the value of PMT. PMT can be any value mutually
-agreed upon by the lender and the borrower. From the equation for PV[1]:
-
-<pre>
- PV[1] = PV + (PMT + (PV + X * PMT) * i),
-</pre>
-
-<p>Several things can be said about PMT.
-
-<ol>
-<li>If PMT = -(PV * i), and X = 0 (end of period payments):
-
-<p>The payment is exactly equal to the interest due and PV[1] = PV. In this case, the borrower
-must make larger future payments to reduce the balance due, or make a single payment, after
-some agreed upon number of payments, with PMT = -PV to completely pay off the loan. This is
-an interest only payment with a balloon payment at the end.
-
-<li>If |PMT| < |PV * i|, and X = 0 and PV > 0
-<p>The payment is insufficient to cover even the interest charged and the balance due grows
-
-<li>If |PMT| > |PV * i|, and X = 0 and PV > 0
-<p>The payment is sufficient to cover the interest charged with a residual amount to be
-applied to reduce the balance due. The larger the residual amount, the faster the loan is
-repaid. For most mortgages or other loans made today, the lender and borrower agree upon
-a certain number of repayment periods and the interest to be charged per payment period.
-The interest may be multiplied by 12 and stated as an annual interest rate. Then the
-lender and borrower want to compute a periodic payment, PMT, which will reduce the balance
-due to zero after the agreed upon number of payments have been made. If N is the agreed
-upon number of periodic payments, then we want to use:
-
-<pre>
- PV * (1 + i)^N + PMT*(1 +iX)*[(1 + i)^N - 1]/i + FV = 0
-</pre>
-
-<p>with FV = 0 to compute PMT:
-
-<pre>
- PMT = -[PV * i * (1 + i)^(N - X)]/[(1 + i)^N - 1]
-</pre>
-
-<p>The value of PMT computed will reduce the balance due to zero after N periodic payments.
-Note that this is strictly true only if PMT is not rounded to the nearest cent as is the
-usual case since it is hard to pay fractional cents. Rounding PMT to the nearest cent has
-an effect on the FV after N payments. If PMT is rounded up, then the final Nth payment
-will be smaller than PMT since the periodic PMTs have paid down the principal faster than
-the exact solution. If PMT is rounded down, then the final Nth payment will be larger than
-the periodic PMTs since the periodic PMTs have paid down the principal slower than the
-exact solution.
-</ol>
-
-<!--#############################################################################-->
-
-<p>With a simple alegebraic re-arrangement, The financial Equation becomes:
-
-<pre>
- 2) [PV + PMT*(1 + iX)/i][(1 + i)^n - 1] + PV + FV = 0
-</pre>
-
-<p>or
-
-<pre>
- 3) (PV + C)*A + PV + FV = 0
-</pre>
-
-<p>where:
-<pre>
- 4) A = (1 + i)^n - 1
-
- 5) B = (1 + iX)/i
-
- 6) C = PMT*B
-</pre>
-
-<p>The form of equation 3) simplifies the calculation procedure for all five
-variables, which are readily solved as follows:
-
-<pre>
- 7) n = ln[(C - FV)/(C + PV)]/ln((1 + i)
-
- 8) PV = -[FV + A*C]/(A + 1)
-
- 9) PMT = -[FV + PV*(A + 1)]/[A*B]
-
- 10) FV = -[PV + A*(PV + C)]
-</pre>
-
-<p>Equations 4), 5) and 6) are computed by the functions in the <tt>"fin.exp"</tt> utility:
-
-<br><tt>_A</tt>
-<br><tt>_B</tt>
-<br><tt>_C</tt>
-
-<p>respectively. Equations 7), 8), 9) and 10) are computed by functions:
-
-<br><tt>_N</tt>
-<br><tt>_PV</tt>
-<br><tt>_PMT</tt>
-<br><tt>_FV</tt>
-
-<p>respectively.
-
-<p>The solution for interest is broken into two cases:
-
-<ol>
-<li>PMT == 0
-<p>Equation 3) can be solved exactly for i:
-
-<pre>
- i = [FV/PV]^(1/n) - 1
-</pre>
-
-<li>PMT != 0
-<p>Since equation 3) cannot be solved explicitly for i in this case, an
-iterative technique must be employed. Newton's method, using exact
-expressions for the function of i and its derivative, are employed. The
-expressions are:
-
-<pre>
- 12) i[k+1] = i[k] - f(i[k])/f'(i[k])
- where: i[k+1] == (k+1)st iteration of i
- i[k] == kth iteration of i
- and:
-
- 13) f(i) = A*(PV+C) + PV + FV
-
- 14) f'(i) = n*D*(PV+C) - (A*C)/i
-
- 15) D = (1 + i)^(n-1) = (A+1)/(1+i)
-</pre>
-
-<p>To start the iterative solution for i, an initial guess must be made
-for the value of i. The closer this guess is to the actual value,
-the fewer iterations will have to be made, and the greater the
-probability that the required solution will be obtained. The initial
-guess for i is obtained as follows:
-
-<ol>
-<li>PV case, PMT*FV >= 0
-
-<pre>
- | n*PMT + PV + FV |
- 16) i[0] = | ----------------|
- | n*PV |
-
- = abs[(n*PMT + PV + FV)/(n*PV)]
-</pre>
-
-<li>FV case, PMT*FV < 0
-<ol>
-<li>PV != 0
-
-<pre>
- | FV - n*PMT |
- 17) i[0] = |---------------------------|
- | 3*[PMT*(n-1)^2 + PV - FV] |
-
- = abs[(FV-n*PMT)/(3*(PMT*(n-1)^2+PV-FV))]
-</pre>
-
-
-<li>PV == 0
-
-<pre>
- | FV + n*PMT |
- 18) i[0] = |---------------------------|
- | 3*[PMT*(n-1)^2 + PV - FV] |
-
- = abs[(FV+n*PMT)/(3*(PMT*(n-1)^2+PV-FV))]
-</pre>
-
-</ol>
-</ol>
-</ol>
-<HR>
-<A HREF="./finutil.html#FinEquation"><IMG SRC="images/back.png" BORDER=0 HEIGHT=13 WIDTH=7>Return</A>
-</body>
diff --git a/libgnucash/doc/finutil.html b/libgnucash/doc/finutil.html
deleted file mode 100644
index ca8687e3bf..0000000000
--- a/libgnucash/doc/finutil.html
+++ /dev/null
@@ -1,2278 +0,0 @@
-<!-- heading 12001 1 -->
-<HTML>
-<HEAD>
-
-<TITLE>Financial Utility Documentation</TITLE>
-</HEAD>
-<BODY>
-<A NAME="TOP"></A>
-<HR size=4>
-<H1>Financial Transaction Utility</H1>
-<!-- <p>Copyright (C) 1990 - 2000 Terry D. Boldt, All Rights Reserved -->
-<HR size=4>
-<dl>
-<dt><A HREF="#FinCalc">Financial Calculator</A></dt>
-<dt><A HREF="#TimeValue">Time Value of Money</A></dt>
- <dd><A HREF="#SimpleInterest">Simple Interest</A></dd>
- <dd><A HREF="#CompoundInterest">Compound Interest</A></dd>
- <dd><A HREF="#PeriodicPayments">Periodic Payments</A></dd>
- <dd><A HREF="#FinTrans">Financial Transactions</A></dd>
-<dt><A HREF="#StandardFinConv">Standard Financial Conventions</A></dt>
-<dt><A HREF="#CashFlowDiag">Cash Flow Diagrams</A></dt>
- <dd><A HREF="#Appreciation">Appreciation</A></dd>
- <dd><A HREF="#Annuity">Annuity</A></dd>
- <dd><A HREF="#Amortization">Amortization</A></dd>
- <dd><A HREF="#Lease">Annuity</A></dd>
-<dt><A HREF="#Interest">Interest</A></dt>
- <dd><A HREF="#CompFreq">Compounding Frequency</A></dd>
- <dd><A HREF="#PayFreq">Payment Frequency</A></dd>
- <dd><A HREF="#DiscIntNARtoEIR">NAR to EIR for Discrete Interest Periods</A></dd>
- <dd><A HREF="#ContIntNARtoEIR">NAR to EIR for Continuous Interest</A></dd>
- <dd><A HREF="#NorVal">Normal CF/PF Values</A></dd>
- <dd><A HREF="#DiscIntEIRtoNAR">EIR to NAR for Discrete Interest Periods</A></dd>
- <dd><A HREF="#ContIntEIRtoNAR">EIR to NAR for Continuous Compounding</A></dd>
-<dt><A HREF="#FinEquation">Financial Equation</A></dt>
- <dd><A HREF="#FinDeriv">Financial Equation Derivation</A></dd>
-<dt><A HREF="#AmortSched">Amortization Schedules</A></dt>
- <dd><A HREF="#ED_IP_Dates">Effective and Initial Payment Dates</A></dd>
- <dd><A HREF="#Eff_PV">Effective Present Value</A></dd>
- <dd><A HREF="#iterative_soltn">Iterative Amortization Schedule</A></dd>
- <dd><A HREF="#AnnualSum">Annual Summary</A></dd>
- <dd><A HREF="#FinalPayment">Final Payment Calculation</A></dd>
- <dd><A HREF="#AmortCases">Amortization Cases</A></dd>
- <dl><dt></dt>
- <dd><A HREF="#ConstOrigData">Constant Repayment to Principal, Original Data</A></dd>
- <dd><A HREF="#ConstNewData">Constant Repayment to Principal, Delayed Repayment</A></dd>
- <dd><A HREF="#OrigData">Original Data Schedule</A></dd>
- <dd><A HREF="#NewFinalPayment">Recomputed Final Payment</A></dd>
- <dd><A HREF="#NewPayment">Recomputed Periodic Payment</A></dd>
- <dd><A HREF="#NewTerm">Recomputed Term</A></dd>
- </dl>
- <dd><A HREF="#DisplaySched">Amortization Schedule Display</A></dd>
-<dt><A HREF="#Usage">Financial Calculator Usage</A></dt>
- <dd><A HREF="#FinCommands">Calculator Commands</A></dd>
- <dd><A HREF="#CalcInput">Calculator Input</A></dd>
- <dd><A HREF="#CalcFun">Calculator Functions</A></dd>
- <dd><A HREF="#UserVar">User Defined Variables</A></dd>
- <dd><A HREF="#Rounding">Rounding</A></dd>
-<dt><A HREF="#Examples">Examples</A></dt>
- <dd><A HREF="#SimpleInt">Simple Interest </A></dd>
- <dd><A HREF="#CompundInt">Compound Interest</A></dd>
- <dd><A HREF="#PeriodicPmt">Periodic Payment</A></dd>
- <dd><A HREF="#ConvMortg">Conventional Mortgage</A></dd>
- <dd><A HREF="#FinalPmt">Final Payment</A></dd>
- <dd><A HREF="#AS_AnnualSum">Conventional Mortgage Amortization Schedule - Annual Summary</A></dd>
- <dd><A HREF="#AS_PeriodicPmt">Conventional Mortgage Amortization Schedule - Periodic Payment Schedule</A></dd>
- <dd><A HREF="#AS_VarAdvPmt">Conventional Mortgage Amortization Schedule - Variable Advanced Payments</A></dd>
- <dd><A HREF="#AS_ConstAdvPmt">Conventional Mortgage Amortization Schedule - Constant Advanced Payments</A></dd>
- <dd><A HREF="#BalloonPmt">Balloon Payment</A></dd>
- <dd><A HREF="#CanadianMortg">Canadian Mortgage</A></dd>
- <dd><A HREF="#EuropeanMortg">European Mortgage</A></dd>
- <dd><A HREF="#BiWeeklySav">Bi-weekly Savings</A></dd>
- <dd><A HREF="#PV_AnnuiytDue">Present Value - Annuity Due</A></dd>
- <dd><A HREF="#EffRate">Effective Rate - 365/360 Basis</A></dd>
- <dd><A HREF="#MortgPoints">Mortgage with "Points"</A></dd>
- <dd><A HREF="#EquivPmt">Equivalent Payments</A></dd>
- <dd><A HREF="#Perpetuity">Perpetuity - Continuous Compounding</A></dd>
- <dd><A HREF="#DevCo">Investment Return</A></dd>
- <dd><A HREF="#Retiement">Retirement Investment</A></dd>
- <dd><A HREF="#PropVal">Property Values</A></dd>
- <dd><A HREF="#CollegeExpenses">College Expenses</A></dd>
- <dd><A HREF="#EffAPY">Certificate of Deposit, Annual Percentage Yield</A></dd>
-<dt><A HREF="#refs">References</A></dt>
-</dl>
-<HR size=4>
-<A NAME="FinCalc">
-<H1>Financial Calculator</H1></A>
-<P>Financial Calculator
-<!-- <p>Copyright (C) 1990 - 2000 Terry D. Boldt, All Rights Reserved -->
-
-<!-- <p>This version for use WITH ANSI.SYS display driver -->
-
-<p>This is a complete financial computation utility to solve for the five
-standard financial values: n, %i, PV, PMT and FV
-<ul>
-<ul>
-<li>n == number of payment periods
-<li>%i == nominal interest rate, NAR, charged
-<li>PV == Present Value of money
-<li>PMT == Periodic Payment
-<li>FV == Future Value of money
-</ul>
-</ul>
-
-<p>In addition, four additional parameters may be specified:
-<ol>
-<li>Compounding Frequency per year, CF. The number of times the interest is compounded
-during the year. The default is 12. The compounding frequency per year may be
-different from the Payment Frequency per year
-
-<li>Payment Frequency per year, PF. The number of payments made in a year. Default is 12.
-
-<li>Discrete or continuous compounding, disc. The default is discrete compounding.
-
-<li>Payments may be at the beginning or end of the payment period, beg. The default is for
-payments to be made at the end of the payment period.
-</ol>
-
-<p>When an amortization schedule is desired, the financial transaction Effective Date, ED,
-and Initial Payment Date, IP, must also be entered.
-
-<p>Canadian and European style mortgages can be handled in a simple,
-straight-forward manner. Standard financial sign conventions are used:
-
-<hr size=4>
-<p align="center">"Money paid out is Negative, Money received is Positive"
-<hr size=4>
-
-<A NAME="TimeValue">
-<H1>Time Value of Money</H1></A>
-<p>If you borrow money, you can expect to pay rent or interest for its use;
-conversely you expect to receive rent interest on money you loan or invest.
-When you rent property, equipment, etc., rental payments are normal; this
-is also true when renting or borrowing money. Therefore, money is
-considered to have a "time value". Money available now, has a greater value
-than money available at some future date because of its rental value or the
-interest that it can produce during the intervening period.
-
-<A NAME="SimpleInterest">
-<H2>Simple Interest</H2></A>
-<p>If you loaned $800 to a friend with an agreement that at the end of one
-year he would would repay you $896, the "time value" you placed on your
-$800 (principal) was $96 (interest) for the one year period (term) of the
-loan. This relationship of principal, interest, and time (term) is most
-frequently expressed as an Annual Percentage Rate (APR). In this case the
-APR was 12.0% [(96/800)*100]. This example illustrates the four basic
-factors involved in a simple interest case. The time period (one year),
-rate (12.0% APR), present value of the principal ($800) and the future
-value of the principal including interest ($896).
-
-<A NAME="CompoundInterest">
-<H2>Compound Interest</H2></A>
-<p>In many cases the interest charge is computed periodically during the term
-of the agreement. For example, money left in a savings account earns
-interest that is periodically added to the principal and in turn earns
-additional interest during succeeding periods. The accumulation of interest
-during the investment period represents compound interest. If the loan
-agreement you made with your friend had specified a "compound interest
-rate" of 12% (compounded monthly) the $800 principal would have earned
-$101.46 interest for the one year period. The value of the original $800
-would be increased by 1% the first month to $808 which in turn would be
-increased by 1% to 816.08 the second month, reaching a future value of
-$901.46 after the twelfth iteration. The monthly compounding of the nominal
-annual rate (NAR) of 12% produces an effective Annual Percentage Rate (APR)
-of 12.683% [(101.46/800)*100]. Interest may be compounded at any regular
-interval; annually, semiannually, monthly, weekly, daily, even continuously
-(a specification in some financial models).
-
-<A NAME="PeriodicPayments">
-<H2>Periodic Payments</H2></A>
-<p>When money is loaned for longer periods of time, it is customary for the
-agreement to require the borrower to make periodic payments to the lender
-during the term of the loan. The payments may be only large enough to repay
-the interest, with the principal due at the end of the loan period (an
-interest only loan), or large enough to fully repay both the interest and
-principal during the term of the loan (a fully amoritized loan). Many loans
-fall somewhere between, with payments that do not fully cover repayment of
-both the principal and interest. These loans require a larger final payment
-(balloon) to complete their amortization. Payments may occur at the
-beginning or end of a payment period. If you and your friend had agreed on
-monthly repayment of the $800 loan at 12% NAR compounded monthly, twelve
-payments of $71.08 for a total of $852.96 would be required to amortize the
-loan. The $101.46 interest from the annual plan is more than the $52.96
-under the monthly plan because under the monthly plan your friend would not
-have had the use of $800 for a full year.
-
-<A NAME="FinTrans">
-<H2>Financial Transactions</H2></A>
-<p>The above paragraphs introduce the basic factors that govern most
-financial transactions; the time period, interest rate, present value,
-payments and the future value. In addition, certain conventions must be
-adhered to: the interest rate must be relative to the compounding frequency
-and payment periods, and the term must be expressed as the total number of
-payments (or compounding periods if there are no payments). Loans, leases,
-mortgages, annuities, savings plans, appreciation, and compound growth are
-among the many financial problems that can be defined in these terms. Some
-transactions do not involve payments, but all of the other factors play a
-part in "time value of money" transactions. When any one of the five (four
-- if no payments are involved) factors is unknown, it can be derived from
-formulas using the known factors.
-
-<A NAME="StandardFinConv">
-<h1>Standard Financial Conventions</h1></A>
-<p>The Standard Financial Conventions are:
-
-<ul>
-<ul>
-<li>Money RECEIVED is a POSITIVE value and is represented by an arrow above
-the line
-
-<li>Money PAID OUT is a NEGATIVE value and is represented by an arrow below
-the line.
-</ul>
-</ul>
-
-<A NAME="CashFlowDiag">
-<h1>Cash Flow Diagrams</h1></A>
-<p>If payments are a part of the transaction, the number of payments must
-equal the number of periods (n).
-
-<p>Payments may be represented as occurring at the end or beginning of the
-periods.
-
-<p>Diagram to visualize the positive and negative cash flows (cash flow
-diagrams):
-
-<p>Amounts shown above the line are positive, received, and amounts shown below the
-line are negative, paid out.
-
-<hr>
-<A NAME="Appreciation">
-<h2>Appreciation</h2></A>
-<br>Appreciation
-<br>Depreciation
-<br>Compound Growth
-<br>Savings Account
-<pre>
- A FV*
- 1 2 3 4 . . . . . . . . . n |
- Period +---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- |
- V
- PV
-</pre>
-
-
-<!--#########################################################################-->
-
-<hr>
-<A NAME="Annuity">
-<h2>Annuity (series of payments)</h2></A>
-<br>Annuity (series of payments)
-<br>Pension Fund
-<br>Savings Plan
-<br>Sinking Fund
-
-<pre>
- PV = 0 A
- |
- Period +---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- | 1 | 2 | 3 | 4 | . | . | . | . | . | . | . | . | . | n
- V V V V V V V V V V V V V V
- PMT PMT PMT PMT PMT PMT PMT PMT PMT PMT PMT PMT PMT PMT
-</pre>
-
-
-<!--#############################################################################-->
-
-<hr>
-<A NAME="Amortization">
-<h2>Amortization</h2></A>
-<br>Direct Reduction Loan
-<br>Mortgage (fully amortized)
-
-<pre>
- PV ^
- | FV=0
- Period +---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- 1 | 2 | 3 | 4 | . | . | . | . | . | . | . | . | . | n |
- V V V V V V V V V V V V V V
- PMT PMT PMT PMT PMT PMT PMT PMT PMT PMT PMT PMT PMT PMT
-</PRE>
-
-<!--#############################################################################-->
-
-<hr>
-<A NAME="Lease">
-<H2>Annuity</H2></a>
-<br>Annuity
-<BR>Lease (with buy back or residual)*
-<br>Loan or Mortgage (with balloon)*
-<pre>
- A FV*
- PMT PMT PMT PMT PMT PMT PMT PMT PMT PMT PMT PMT PMT | +
- A A A A A A A A A A A A A A PMT
- 1 | 2 | 3 | 4 | . | . | . | . | . | . | . | . | . | n |
- Period +---+---+---+---+---+---+---+---+---+---+---+---+---+---+
- |
- V
- PV
-</pre>
-
-<!--#############################################################################-->
-
-<hr>
-<A NAME="Interest">
-<h1>Interest</h1></A>
-<p>Before discussing the financial equation, we will discuss interest. Most
-financial transactions utilize a nominal interest rate, NAR, i.e., the interest
-rate per year. The NAR must be converted to the interest rate per payment
-period and the compounding accounted for before it can be used in computing
-an interest payment. After this conversion process, the interest used is the
-effective interest rate, EIR. In converting NAR to EIR, there are two concepts
-to discuss first, the Compounding Frequency and the Payment Frequency and
-whether the interest is compounded in discrete intervals or continuously.
-
-<A NAME="CompFreq">
-<h2>Compounding Frequency</h2></A>
-<p>The compounding Frequency, CF, is simply the number of times per year, the
-monies in the financial transaction are compounded. In the U.S., monies
-are usually compounded daily on bank deposits, and monthly on loans. Sometimes
-long term deposits are compounded quarterly or weekly.
-
-<A NAME="PayFreq">
-<h2>Payment Frequency</h2></A>
-<p>The Payment Frequency, PF, is simply how often during a year payments are
-made in the transaction. Payments are usually scheduled on a regular basis
-and can be made at the beginning or end of the payment period. If made at
-the beginning of the payment period, interest must be applied to the payment
-as well as any previous money paid or money still owed.
-
-<A NAME="NorVal">
-<h2>Normal CF/PF Values</h2></A>
-<p>Normal values for CF and PF are:
-<ul>
-<ul>
-<li>1 == annual
-<li>2 == semi-annual
-<li>3 == tri-annual
-<li>4 == quaterly
-<li>6 == bi-monthly
-<li>12 == monthly
-<li>24 == semi-monthly
-<li>26 == bi-weekly
-<li>52 == weekly
-<li>360 == daily
-<li>365 == daily
-</ul>
-</ul>
-
-<p>The Compounding Frequency per year, CF, need not be identical to the
-Payment Frequency per year, PF. Also,
-Interest may be compounded in either discrete intervals or continuously
-compounded and payments may be made at the beginning of the payment period or at the
-end of the payment period.
-
-<p>CF and PF are defaulted to 12. The default is for discrete interest intervals
-and payments are defaulted to the end of the payment period.
-
-<p>When a solution for n, PV, PMT or FV is required, the nominal interest
-rate, i, must first be converted to the effective interest rate per payment
-period. This rate, ieff, is then used to compute the selected variable. To
-convert i to ieff, the following expressions are used:
-
-<A NAME="DiscIntNARtoEIR">
-<h2>NAR to EIR for Discrete Interest Periods</h2></A>
-<p>To convert NAR to EIR for discrete interest periods:
-
-<p>ieff = (1 + i/CF)^(CF/PF) - 1
-
-<A NAME="ContIntNARtoEIR">
-<h2>NAR to EIR for Continuous Compounding</h2></A>
-<p>to convert NAR to EIR for Continuous Compounding:
-
-<p>ieff = e^(i/PF) - 1 = exp(i/PF) - 1
-
-<p>When interest is computed, the computation produces the effective interest
-rate, ieff. This value must then be converted to the nominal interest rate.
-Function _I in the <tt>"fin.exp"</tt> utility returns the nominal interest
-rate NOT the effective interest rate. ieff is converted to i using the following expressions:
-
-<A NAME="DiscIntEIRtoNAR">
-<h2>EIR to NAR for Discrete Interest Periods</h2></A>
-<p>To convert EIR to NAR for discrete interest periods:
-
-<p>i = CF*([(1+ieff)^(PF/CF) - 1)
-
-<A NAME="ContIntEIRtoNAR">
-<h2>EIR to NAR for Continuous Compounding</h2></A>
-<p>To convert EIR to NAR for continuous compounding:
-
-<p>i = ln((1+ieff)^PF)
-
-<!--#############################################################################-->
-
-<!--#############################################################################-->
-
-<A NAME="FinEquation">
-<H1>Financial Equation</h1></A>
-<p>NOTE: in the equations below for the financial transaction, all interest rates
-are the effective interest rate, <tt>ieff</tt>. The symbol will be shortned to just <tt>i</tt>.
-
-<p>The financial equation used to inter-relate n,i,PV,PMT and FV is:
-
-<p>1) PV*(1 + i)^n + PMT*(1 + iX)*[(1+i)^n - 1]/i + FV = 0
-
-<pre>
- Where: X == 0 for end of period payments, and
- X == 1 for beginning of period payments
- n == number of payment periods
- i == effective interest rate for payment period
- PV == Present Value
- PMT == periodic payment
- FV == Future Value
-</pre>
-
-<!--#############################################################################-->
-<A NAME="FinDeriv">
-<h2>Financial Equation Derivation</h2></A>
-<p>The derivation of the financial equation is contained in the
-<A HREF="finderv.html#TOP">Financial Equations</A>
-section.
-
-
-<!--#############################################################################-->
-
-<A NAME="AmortSched">
-<h1>Amortization Schedules.</h1></A>
-
-<A NAME="ED_IP_Dates">
-<h2>Effective and Initial Payment Dates</h2></A>
-<p>Financial Transactions have an effective Date, ED, and an Initial Payment
-Date, IP. ED may or may not be the same as IP, but IP is always the same
-or later than ED. Most financial transaction calculators assume that
-IP is equal to ED for beginning of period payments or at the end of the
-first payment period for end of period payments.
-
-<p>This is not always true. IP may be delayed for financial reasons such as cash
-flow or accounting calendar. The subsequent payments then follow the
-agreed upon periodicity.
-
-<A name="Eff_PV">
-<h2>Effective Present Value</h2></A>
-<p>Since money has a time value, the "delayed" IP
-must be accounted for. Computing an "Effective PV", pve, is one means of
-handling a delayed IP.
-
-<p>If
-
-<pre>
-ED_jdn == the Julian Day Number of ED, and
-IP_jdn == the Julian Day Number of IP
-</pre>
-
-<p>pve is computed as:
-
-<pre>
- pve = pv*(1 + i)^(s*PF/d*CF)
-
- Where: d = length of the payment period in days, and
- s = IP_jdn - ED_jdn - d*(1 - X)
-</pre>
-
-<A name="iterative_soltn">
-<h2>Iterative Amortization Schedule</h2></A>
-<p>Computing an amortization Schedule for a given financial transaction is
-simply applying the basic equation iteratively for each payment period:
-
-<pre>
- PV[n] = PV[n-1] + (PMT + (PV[n-1] + X * PMT) * i)
- = PV[n-1] * (1 + i) + PMT * (1 + iX)
- for n >= 1
-</pre>
-
-<p>At the end of each iteration, PV[n] is rounded to the nearest cent. For
-each payment period, the interest due may be computed separately as:
-
-<pre>
- ID[n] = (PV[n-1] + X * PMT) * i
-</pre>
-
-<p>and rounded to the nearest cent. PV[n] then becomes:
-
-<pre>
- PV[n] = PV[n-1] + PMT + ID[n]
-</pre>
-
-<A name="AnnualSum">
-<h2>Annual Summary</h2></A>
-<p>For those cases where a yearly summary only is desired, it is not necessary
-to compute each transaction for each payment period, rather the PV may be
-be computed for the beginning of each year, PV[yr], and the FV computed for
-the end of the year, FV[yr]. The interest paid during the year is the computed as:
-
-<pre>
- ID[yr] = (NP * PMT) + PV[yr] + FV[yr]
- where: NP == number of payments during year
- == PF for a full year of payments
-</pre>
-
-<A name="FinalPayment">
-<h2>Final Payment Calculation</h2></A>
-<p>Since the final payment may not be equal to the periodic payment, the final
-payment must be computed separately as follows. Two derivations are given below
-for the final payment equation. Both derivations are given below since one or
-the other may be clearer to some readers. Both derivations are essentially
-the same, they just have different starting points. The first is the fastest to derive.
-
-<p>Note, for the purposes of computing an amortization table, the number of periodic
-payments is assumed to be an integral value. For most cases this is true, the two
-principles in any transaction usually agree upon a certain term or number of periodic
-payments. In some calculations, however, this may not hold. In all of the calculations
-below, n is assumed integral and in the gnucash implementation, the following calculation
-is performed to assure this fact:
-
-<pre>
- n = int(n)
-</pre>
-
-<ol>
-<li>final_pmt == final payment @ payment n
-<p>From the basic financial equation derived above:
-
-<pre>
- PV[n] = PV[n-1]*(1 + i) + final_pmt * (1 + iX), i == effective interest rate
-</pre>
-
-<p>solving for final_pmt, we have:
-<p>NOTE: FV[n] = -PV[n], for any n
-
-<pre>
- final_pmt * (1 + iX) = PV[n] - PV[n-1]*(1 + i)
- = FV[n-1]*(1 + i) - FV[n]
- final_pmt = FV[n-1]*(1+i)/(1 + iX) - FV[n]/(1 + iX)
-
- final_pmt = FV[n-1]*(1 + i) - FV[n], for X == 0, end of period payments
- = FV[n-1] - FV[n]/(1 + i), for X == 1, beginning of period payments
-</pre>
-
-<li>final_pmt == final payment @ payment n
-
-<pre>
- i[n] == interest due @ payment n
- i[n] = (PV[n-1] + X * final_pmt) * i, i == effective interest rate
- = (X * final_pmt - FV[n]) * i
-</pre>
-
-<p>Now the final payment is the sum of the interest due, plus the present value
-at the next to last payment plus any residual future value after the last payment:
-
-<pre>
- final_pmt = -i[n] - PV[n-1] - FV[n]
- = FV[n-1] - i[n] - FV[n]
- = FV[n-1] - (X *final_pmt - FV[n-1])*i - FV[n]
- = FV[n-1]*(1 + i) - X*final_pmt*i - FV[n]
-</pre>
-
-<p>solving for final_pmt:
-
-<pre>
- final_pmt*(1 + iX) = FV[n-1]*(1 + i) - FV[n]
- final_pmt = FV[n-1]*(1 + i)/(1 + iX) - FV[n]/(1 + iX)
-
- final_pmt = FV[n-1]*(1 + i) - FV[n], for X == 0, end of period payments
- = FV[n-1] - FV[n]/(1 + i), for X == 1, beginning of period payments
-</pre>
-</ol>
-
-<!--================================================================================-->
-
-<A name="AmortCases">
-<h2>Amortization Cases</h2></A>
-
-<p>The amortization schedule is computed for six different situations:
-
-<ol>
-<A name="ConstOrigData">
-<h3>Constant Repayment to Principal, Original Data</h3>
-<li>In a constant repayment to principal loan, each payment varies. A constant amount
-is applied to the principal for each payment, usually equal to the originating present value
-divided by the number of repayment periods, and the interest for the payment period is
-added to the constant principal payment. The derivation of the equation for this type
-is contained in the <A HREF="constderv.html#TOP">Constant Repayment Equations</A> section. This
-case computes the amortization schedule with the original loan data and a constant repayment
-to principal.
-
-<A name="ConstNewData">
-<h3>Constant Repayment to Principal, Delayed Repayment</h3>
-<li>In a constant repayment to principal loan, each payment varies. A constant amount
-is applied to the principal for each payment, usually equal to the originating present value
-divided by the number of repayment periods, and the interest for the payment period is
-added to the constant principal payment. The derivation of the equation for this type
-is contained in the <A HREF="constderv.html#TOP">Constant Repayment Equations</A> section. This
-case computes the amortization schedule with the delayed loan data and a constant repayment
-to principal.
-
-<A name="OrigData">
-<h3>Original Data Schedule</h3></A>
-<li>The original financial data is used. This ignores any possible agjustment to
-the Present value due to any delay in the initial payment. This is quite
-common in mortgages where end of period payments are used and the first
-payment is scheduled for the end of the first whole period, i.e., any
-partial payment period from ED to the beginning of the next payment period
-is ignored.
-
-<A name="NewFinalPayment">
-<h3>Recomputed Final Payment</h3></A>
-<li>The original periodic payment is used, the Present Value is adjusted for the
-delayed Initial Payment. The total number of payments remains the same. The
-final payment is adjusted to bring the balance into agreement with the
-agreed upon final Future Value.
-
-<A name="NewPayment">
-<h3>Recomputed Periodic Payment</h3></A>
-<li>A new periodic payment is computed based upon the adjusted Present Value, the
-originally agreed upon number of total payments and the agreed upon Future Value.
-The new periodic payments are computed to minimize the final payment in accordance
-with the Future Value after the last payment.
-
-<A name="NewTerm">
-<h3>Recomputed Term</h3></A>
-<li>The original periodic payment is retained and a new number of total payments is computed
-based upon the adjusted Present Value and the agreed upon Future Value.
-</ol>
-
-<a name="DisplaySched">
-<h2>Amortization Schedule Display</h2></A>
-<p>The amortization schedule may be computed and displayed in three manners:
-
-<ol>
-<li>The payment#, interest paid, principal paid and remaining PV for each payment period
-are computed and displayed.
-<p>At the end of each year a summary is computed and displayed
-and the total interest paid is displayed at the end.
-
-<li>A summary is computed and displayed for each year. The interest paid during the
-year is computed and displayed as well as the remaining balance at years end.
-<p>The total interest paid is displayed at the end.
-
-<li>An amortization schedule is computed and displayed for a common method of
-advanced payment of principal.
-<p>In this amortization schedule, the principal for the
-next payment is computed and added into the current payment. This method will
-cut the number of total payments in half and will cut the interest paid almost
-in half.
-<p>For mortgages, this method of prepayment has the advantage of keeping
-the total payments small during the initial payment periods
-The payments grow until the last payment period when presumably the borrower
-can afford larger payments.
-</ol>
-
-<!--================================================================================-->
-<p>NOTE: For Payment Frequencies, PF, semi-monthly or less, i.e., PF == 12 or PF == 24,
-a 360 day calendar year and 30 day month are used. For Payment Frequencies, PF,
-greater than semi-monthly, PF > 24, the actual number of days per year and per payment
-period are used. The actual values are computed using the built-in 'jdn' function
-
-<!--#############################################################################-->
-<a name="Usage">
-<h1>Financial Calculator Usage</h1></a>
-<p>the Financial Calculator is run as a QTAwk utility. If input is to be interactive and
-from the keyboard, do not specify any input files on the command line. The financial
-calcutlator reads all input from the standard input file. The calculator is started
-as:
-
-<pre>
-QTAwk -f fin.exp
-</pre>
-
-<p>The calculator will clear the display screen and display a two screen help:
-
-<pre>
-Financial Calculator
-Copyright (C) 1990 - 1997 Terry D. Boldt, All Rights Reserved.
-To compute Loan Quantities:
-N ==> to compute # payment periods from i, pv, pmt, fv
-_N(i,pv,pmt,fv,CF,PF,disc,bep) ==> to compute # payment periods
-I ==> to compute nominal interest rate from n, pv, pmt, fv, CF, PF, disc, bep
-_I(n,pv,pmt,fv,CF,PF,disc,bep) ==> to compute interest
-PV ==> to compute Present Value from n, i, pmt, fv, CF, PF, disc, bep
-_PV(n,i,pmt,fv) ==> to compute Present Value
-PMT ==> to compute Payment from n, i, pv, fv, CF, PF, disc, bep
-_PMT(n,i,pv,fv,CF,PF,disc,bep) ==> to compute Payment
-FV ==> to compute Future Value from n, i, pv, pmt, CF, PF, disc, bep
-_FV(n,i,pv,pmt,CF,PF,disc,bep) ==> to compute Future Value
-Press Any Key to Continue
-</pre>
-
-<p>The first screen displays the calculator commands which are available. Press any key
-and a second screen displays the variables defined by the calculator and which must be
-set by the user to use the financial calculator functions.
-
-<pre>
-[Aa](mort)? to Compute Amortization Schedule
-[Cc](ls)? to Clear Screen
-[Dd](efault)? to Re-Initialize
-[Hh](elp) to Display This Help
-[Qq](uit)? to Quit
-[Ss](tatus)? to Display Status of Computations
-[Uu](ser) Display User Defined Variables
-
-Variables to set:
-n == number of periodic payments
-i == interest per compouding interval
-pv == present value
-pmt == periodic payment
-fv == future value
-disc == TRUE/FALSE == discrete/continuous compounding
-bep == TRUE/FALSE == beginning of period/end of period payments
-CF == compounding frequency per year
-PF == payment frequency per year
-
-ED == effective date of transaction, mm/dd/yyyy
-IP == initial payment date of transaction, mm/dd/yyyy
-</pre>
-
-<a name="FinCommands">
-<h2>Calculator Commands</h2></a>
-<p>The financial calculator commands available are listed above and below.
-
-<p>Note that the first letter of the command is all that is necessary to activate the
-desired function.
-
-<ol>
-<li>[Aa](mort)? to Compute Amortization Schedule
-<br>After all financial variables have been defined as well as the transaction dates,
-the amortization schedule can be computed for all financial transactions in which
-one would make sense.
-<li>[Cc](ls)? to Clear Screen
-<br>This command clears the screen and displays the copyright.
-<li>[Dd](efault)? to Re-Initialize
-<br>This command re-initializes all calculator variables to their start-up values.
-<li>[Hh](elp) to Display This Help
-<br>This command is used to display the start-up help screens at any time.
-<li>[Qq](uit)? to Quit
-<br>When the calculator is used interactively from the keyboard, this command allows
-the user to terminate the calculator session.
-<li>[Ss](tatus)? to Display Status of Computations
-<br>This command displays the status of the calculator variables. A typical status display
-would be:
-
-<pre>
-Financial Calculator
-Copyright (C) 1990 - 1997 Terry D. Boldt, All Rights Reserved
-Current Financial Calculator Status:
-Compounding Frequency: (CF) 12
-Payment Frequency: (PF) 12
-Compounding: Discrete (disc = TRUE)
-Payments: End of Period (bep = FALSE)
-Number of Payment Periods (n): 360 (Years: 30)
-Nominal Annual Interest Rate (i): 7.25
- Effective Interest Rate Per Payment Period: 0.00604167
-Present Value (pv): 233,350.00
-Periodic Payment (pmt): -1,591.86
-Future Value (fv): 0.00
-Effective Date: Tue Jun 04 00:00:00 1996(2450239)
-Initial Payment Date: Thu Aug 01 00:00:00 1996(2450297)
-<>
-</pre>
-<li>[Uu](ser) Display User Defined Variables
-<br>If any variables have been defined by the user, this command displays their names and
-values.
-</ol>
-
-<a name="CalcInput">
-<h2>Calculator Input</h2></a>
-<p>The calculator displays an <tt>input prompt</tt> whenever it is waiting for input
-from the keyboard. The <tt>input prompt</tt> is simply <tt><></tt>. The desired
-input is typed at the keyboard and the enter key pressed. The result of calculating the
-value of the input line is then displayed by the calculator. For example, if the user wanted
-to set the value of the nominal interest in the calculator to 6.25, the following line would be
-input to the calculator:
-
-<p><tt>i=6.25</tt>.
-
-<p>A semi-colon at the end of the input is optional.
-The line as seen on the display with the calculator input prompt would be:
-
-<pre>
-<>i = 6.25
- 6.25
-</pre>
-
-<p>Note that the calculator displays the value of the result, 6.25 in this case.
-
-<p>The calculator is controlled by setting the calculator variables to the desired values
-and <tt>"executing"</tt> the calculator functions to derive the values for the unknown
-variables. For example, for a conventional home mortgage for $233,350.00 with a thirty year
-term, nominal annual rate of 7.25%, n, i, pv and fv are known:
-
-<pre>
-n == 360 == 12 * 30
-i == 7.25
-pv= 233350
-fv = 0
-</pre>
-
-<p>The payments to completely pay off the mortgage with the 360 periodic payments is desired.
-To compute the desired periodic payment value, the <tt>PMT</tt> function is used. Since the
-function has no defined arguments, in invoking the function no arguments are specified. The
-complete session to input the desired values and calculate the periodic payment value would
-appear as:
-
-<pre>
-<>n=30*12
- 360
-<>i=7.25
- 7.25
-<>pv=233350
- 233,350
-<>PMT
- -1,591.86
-</pre>
-
-<p>Note that the input may contain computations, <tt>n=30*12</tt>. In addition, any QTAwk
-built-in function may be specified and any functions defined in the financial calculator.
-This can be handy for computing intermediate values or other results from the results of
-the calculator.
-
-<p>Note that the output of the <tt>PMT</tt> function is rounded to the nearest cent. Over the
-thirty year term of the payback, the rounding will affect the last payment. To determine
-the balance due, fv, after 359 payment have been made, decrement n by 1 and compute the
-future value:
-
-<pre>
-<>n-=1
- 359
-<>FV
- -1,580.20
-<>n+=1
- 360
-<>FV
- 2.12
-<>
-</pre>
-
-<p>The future value after 359 payments is less than the periodic payment and a full final payment
-will overpay the loan. The final FV computation with n restored to 360 shows an overpayment
-of 2.12.
-
-<a name="CalcFun">
-<h2>Calculator Functions</h2></a>
-<p>The calculator functions:
-
-<pre>
-N
-I
-PV
-PMT
-FV
-</pre>
-
-<p>can be used to calculate the variable with the corresponding lower case name, using the
-values of the other four calculator variables which have already been set. In addition, the
-calculator functions:
-
-<pre>
-_N(i,pv,pmt,fv,CF,PF,disc,bep)
-_I(n,pv,pmt,fv,CF,PF,disc,bep)
-_PV(n,i,pmt,fv,CF,PF,disc,bep)
-_PMT(n,i,pv,fv,CF,PF,disc,bep)
-_FV(n,i,pv,pmt,CF,PF,disc,bep)
-</pre>
-
-<p>can be used to compute the value of the corresponding quantity for any specified value
-of the input arguments.
-
-<p>There are three differences between the functions <tt>N, I, PV, PMT, FV</tt> and the
-functions
-<tt>_N(i,pv,pmt,fv,CF,PF,disc,bep), _I(n,pv,pmt,fv,CF,PF,disc,bep), _PV(n,i,pmt,fv,CF,PF,disc,bep),
-_PMT(n,i,pv,fv,CF,PF,disc,bep), _FV(n,i,pv,pmt,CF,PF,disc,bep)</tt>.
-<ol>
-<li>The first set of functions take no arguments and
-use the calculator variables, n, i, pv, pmt, fv, CF, PF, disc
-and bep to compute the desired value. The second set of functions use the values passed in
-the function arguments. The first set of functions call the second set with the necessary
-arguments.
-<li>The first set of functions round the computed value returned by the call to the second set
-of functions to the nearest cent. The second set of functions perform no rounding.
-<li>The first set of functions set the calculator variables with the corresponding lower case name
-to the value computed. The second set of functions set no global variable values.
-</ol>
-
-<a name="UserVar">
-<h2>User Defined Variables</h2></a>
-<p>User defined variables may be defined and their values set to a desired qunatity. For example,
-to save computation results before re-initializing the calculator to obtain other results. If
-the user desired to compare the periodic payments necessary to fully pay the conventional
-mortgage cited above, the payment computed above could be saved in the variable
-<tt>end_pmt</tt>, the payments set to beginning of period payments and the new payment
-computed. The new value could be set into the variable <tt>beg_pmt</tt>. The two payments
-could then be viewed with the <tt>u</tt> command. The difference could then be computed
-between the two payment methods:
-
-<pre>
-<>n=30*12
- 360
-<>i=7.25
- 7.25
-<>pv=233350
- 233,350
-<>PMT
- -1,591.86
-<>end_pmt=pmt
- -1,591.86
-<>bep=1
- 1
-<>PMT
- -1,582.30
-<>beg_pmt=pmt
- -1,582.30
-<>u
-
-Financial Calculator
-Copyright (C) 1990 - 1997 Terry D. Boldt, All Rights Reserved.
-Current Financial Calculator Status:
-User Defined Variables:
-end_pmt == -1,591.86
-beg_pmt == -1,582.30
-<>beg_pmt-end_pmt
- 9.56
-<>
-</pre>
-
-<p>The financial calculator is thus a true calculator and can be used for computations
-desired by the user beyond those performed by the functions of the utility.
-
-<a name="Rounding">
-<h2>Rounding</h2></a>
-<p>Note that the output of the calculator is rounded to the nearest cent for floating
-point values. Sometimes the full accuracy of the value is desired. This can be obtained
-by redefing the calculator variable <tt>ofmt</tt> to the string "%.15g". You might want to
-save the current value in a user variable for resetting. For example in the above
-conventional mortgage, the exact value of the periodic payment can be displayed as:
-
-<pre>
-<>sofmt=ofmt
- "%.2f"
-<>ofmt="%.15g"
- "%.15g"
-<>pmt=_PMT(n,i,pv,fv,CF,PF,disc,bep)
- -1,591.85834951112
-<>ofmt=sofmt
- "%.2f"
-<>
-</pre>
-
-<p>Note that the current value of the output format string, <tt>ofmt</tt>, has been
-saved in the variable, <tt>sofmt</tt>, and later restored.
-
-<a name="Examples">
-<h1>Examples</h1></a>
-<!-- Note: in the following examples, the user input is preceded by the prompt -->
-<!-- "<>". The result of evaluating the input expression is then displayed. -->
-<!-- I have taken the liberty of including comments in the example -->
-<!-- input/output sessions by preceding with '#'. Thus, for the line: -->
-<!-- <>n=5 #set number of periods -->
-<!-- the comment that setting the number of periods is not really input and the true-->
-<!-- input is only: -->
-<!-- <>n=5 -->
-
-<a name="SimpleInt">
-<h2>Simple Interest </h2></a>
-<p>Simple Interest
-<p> Find the annual simple interest rate (%) for an $800 loan to be repayed at the
- end of one year with a single payment of $896.
-<pre>
- <>d
- <>CF=PF=1
- 1
- <>n=1
- 1
- <>pv=-800
- -800
- <>fv=896
- 896
- <>I
- 12.00
-</pre>
-
-<a name="CompundInt">
-<h2>Compound Interest</h2></a>
-<p>Compound Interest
-<p>Find the future value of $800 after one year at a nominal rate of 12%
- compounded monthly. No payments are specified, so the payment frequency is
- set equal to the compounding frequency at the default values.
-<pre>
- <>d
- <>n=12
- 12
- <>i=12
- 12
- <>pv=-800
- -800
- <>FV
- 901.46
-</pre>
-
-<a name="PeriodicPmt">
-<h2>Periodic Payment</h2></a>
-<p>Periodic Payment
-<p>Find the monthly end-of-period payment required to fully amortize the loan
- in Example 2. A fully amortized loan has a future value of zero.
-<pre>
- <>fv=0
- 0
- <>PMT
- 71.08
-</pre>
-
-<a name="ConvMortg">
-<h2>Conventional Mortgage</h2></a>
-<p>Conventional Mortgage
-<p>Find the number of monthly payments necessary to fully amortize a loan of
- $100,000 at a nominal rate of 13.25% compounded monthly, if monthly end-of-period
- payments of $1125.75 are made.
-<pre>
- <>d
- <>i=13.25
- 13.25
- <>pv=100000
- 100,000
- <>pmt=-1125.75
- -1,125.75
- <>N
- 360.10
-</pre>
-
-<a name="FinalPmt">
-<h2>Final Payment</h2></a>
-<p>Final Payment
-<p>Using the data in the above example, find the amount of the final payment if n is
-changed to 360. The final payment will be equal to the regular payment plus
-any balance, future value, remaining at the end of period number 360.
-<pre>
- <>n=int(n)
- 360
- <>FV
- -108.87
- <>pmt+fv
- -1,234.62
-</pre>
-
-<a name="AS_AnnualSum">
-<h2>Conventional Mortgage Amortization Schedule - Annual Summary</h2></a>
-<p>Conventional Mortgage Amortization Schedule - Annual Summary
-<p>Using the data from the loan in the previous example, compute the amortization
-schedule when the
-Effective date of the loan is June 6, 1996 and the initial payment is
-made on August 1, 1996. Ignore any change in the PV due to the delayed
-initial payment caused by the partial payment period from June 6 to July 1.
-
-<pre>
- <>ED=6/6/1996
- Effective Date set: (2450241) Thu Jun 06 00:00:00 1996
- <>IP=8/1/96
- Initial Payment Date set: (2450297) Thu Aug 01 00:00:00 1996
- <>a
- Effective Date: Thu Jun 06 00:00:00 1996
- Initial Payment Date: Thu Aug 01 00:00:00 1996
- The amortization options are:
- The Old Present Value (pv) was: 100,000.00
- The Old Periodic Payment (pmt) was: -1,125.75
- The Old Future Value (fv) was: -108.87
- 1: Amortize with Original Transaction Values
- and final payment: -1,125.75
-
- The New Present Value (pve) is: 100,919.30
- The New Periodic Payment (pmt) is: -1,136.10
- 2: Amortize with Original Periodic Payment
- and final payment: -49,023.68
- 3: Amortize with New Periodic Payment
- and final payment: -1,132.57
- 4: Amortize with Original Periodic Payment,
- new number of total payments (n): 417
- and final payment: -2,090.27
-
- Enter choice 1, 2, 3 or 4: <>
-</pre>
-
-<p>Press '1' to choose option 1:
-
-<pre>
- Amortization Schedule:
- Yearly, y, per Payment, p, or Advanced Payment, a, Amortization
- Enter choice y, p or a:
- <>
-</pre>
-
-<p>Press 'y' for an annual summary:
-
-<pre>
- Enter Filename for Amortization Schedule.
- (null string uses Standard Output):
-</pre>
-
-<p>Press enter to display output on screen:
-
-<pre>
- Amortization Table
- Effective Date: Thu Jun 06 00:00:00 1996
- Initial Payment Date: Thu Aug 01 00:00:00 1996
- Compounding Frequency per year: 12
- Payment Frequency per year: 12
- Compounding: Discrete
- Payments: End of Period
- Payments (359): -1,125.75
- Final payment (# 360): -1,125.75
- Nominal Annual Interest Rate: 13.25
- Effective Interest Rate Per Payment Period: 0.0110417
- Present Value: 100,000.00
- Year Interest Ending Balance
- 1996 -5,518.42 -99,889.67
- 1997 -13,218.14 -99,598.81
- 1998 -13,177.17 -99,266.98
- 1999 -13,130.43 -98,888.41
- 2000 -13,077.11 -98,456.52
- 2001 -13,016.28 -97,963.80
- 2002 -12,946.88 -97,401.68
- 2003 -12,867.70 -96,760.38
- 2004 -12,777.38 -96,028.76
- 2005 -12,674.33 -95,194.09
- 2006 -12,556.76 -94,241.85
- 2007 -12,422.64 -93,155.49
- 2008 -12,269.63 -91,916.12
- 2009 -12,095.06 -90,502.18
- 2010 -11,895.91 -88,889.09
- 2011 -11,668.70 -87,048.79
- 2012 -11,409.50 -84,949.29
- 2013 -11,113.78 -82,554.07
- 2014 -10,776.41 -79,821.48
- 2015 -10,391.53 -76,704.01
- 2016 -9,952.43 -73,147.44
- 2017 -9,451.49 -69,089.93
- 2018 -8,879.99 -64,460.92
- 2019 -8,227.99 -59,179.91
- 2020 -7,484.16 -53,155.07
- 2021 -6,635.56 -46,281.63
- 2022 -5,667.43 -38,440.06
- 2023 -4,562.94 -29,494.00
- 2024 -3,302.89 -19,287.89
- 2025 -1,865.36 -7,644.25
- 2026 -236.00 -108.87
-
- Total Interest: -305,270.00
-</pre>
-
-<p> NOTE: The amortization table leaves the FV as it was when the amortization
-function was entered. Thus, a balance of 108.87 is due at the end of the
-table. To completely pay the loan, set fv to 0.0:
-<pre>
-<>fv=0
- 0
-<>a
- Effective Date: Thu Jun 06 00:00:00 1996
- Initial Payment Date: Thu Aug 01 00:00:00 1996
- The amortization options are:
- The Old Present Value (pv) was: 100,000.00
- The Old Periodic Payment (pmt) was: -1,125.75
- The Old Future Value (fv) was: 0.00
- 1: Amortize with Original Transaction Values
- and final payment: -1,234.62
-
- The New Present Value (pve) is: 100,919.30
- The New Periodic Payment (pmt) is: -1,136.12
- 2: Amortize with Original Periodic Payment
- and final payment: -49,132.55
- 3: Amortize with New Periodic Payment
- and final payment: -1,148.90
- 4: Amortize with Original Periodic Payment,
- new number of total payments (n): 417
- and final payment: -2,199.14
-
- Enter choice 1, 2, 3 or 4: <>
-</pre>
-
-<p>Press '1' for option 1:
-
-<pre>
- Amortization Schedule:
- Yearly, y, per Payment, p, or Advanced Payment, a, Amortization
- Enter choice y, p or a:
- <>
-</pre>
-
-<p>Press 'y' for annual summary:
-
-<pre>
- Enter Filename for Amortization Schedule.
- (null string uses Standard Output):
-</pre>
-
-<p>Press enter to display output on screen:
-
-<pre>
- Amortization Table
- Effective Date: Thu Jun 06 00:00:00 1996
- Initial Payment Date: Thu Aug 01 00:00:00 1996
- Compounding Frequency per year: 12
- Payment Frequency per year: 12
- Compounding: Discrete
- Payments: End of Period
- Payments (359): -1,125.75
- Final payment (# 360): -1,234.62
- Nominal Annual Interest Rate: 13.25
- Effective Interest Rate Per Payment Period: 0.0110417
- Present Value: 100,000.00
- Year Interest Ending Balance
- 1996 -5,518.42 -99,889.67
- 1997 -13,218.14 -99,598.81
- 1998 -13,177.17 -99,266.98
- 1999 -13,130.43 -98,888.41
- 2000 -13,077.11 -98,456.52
- 2001 -13,016.28 -97,963.80
- 2002 -12,946.88 -97,401.68
- 2003 -12,867.70 -96,760.38
- 2004 -12,777.38 -96,028.76
- 2005 -12,674.33 -95,194.09
- 2006 -12,556.76 -94,241.85
- 2007 -12,422.64 -93,155.49
- 2008 -12,269.63 -91,916.12
- 2009 -12,095.06 -90,502.18
- 2010 -11,895.91 -88,889.09
- 2011 -11,668.70 -87,048.79
- 2012 -11,409.50 -84,949.29
- 2013 -11,113.78 -82,554.07
- 2014 -10,776.41 -79,821.48
- 2015 -10,391.53 -76,704.01
- 2016 -9,952.43 -73,147.44
- 2017 -9,451.49 -69,089.93
- 2018 -8,879.99 -64,460.92
- 2019 -8,227.99 -59,179.91
- 2020 -7,484.16 -53,155.07
- 2021 -6,635.56 -46,281.63
- 2022 -5,667.43 -38,440.06
- 2023 -4,562.94 -29,494.00
- 2024 -3,302.89 -19,287.89
- 2025 -1,865.36 -7,644.25
- 2026 -344.87 0.00
-
- Total Interest: -305,378.87
-</pre>
-
-<p>Note that now the final payment differs from the periodic payment and
-the loan has been fully paid off.
-
-<a name="AS_PeriodicPmt">
-<h2>Conventional Mortgage Amortization Schedule - Periodic Payment Schedule</h2></a>
-<p>Conventional Mortgage Amortization Schedule - Periodic Payment Schedule
-<p>Using the loan in the previous example, compute the amortization table and display the
-results for each payment period.
-As in example 6, ignore any increase in the PV due to the
-delayed IP.
-
-<pre>
-<>
- Amortization Table
- Effective Date: Thu Jun 06 00:00:00 1996
- Initial Payment Date: Thu Aug 01 00:00:00 1996
- Compounding Frequency per year: 12
- Payment Frequency per year: 12
- Compounding: Discrete
- Payments: End of Period
- Payments (359): -1,125.75
- Final payment (# 360): -1,234.62
- Nominal Annual Interest Rate: 13.25
- Effective Interest Rate Per Payment Period: 0.0110417
- Present Value: 100,000.00
- Pmt# Interest Principal Balance
- 1 -1,104.17 -21.58 -99,978.42
- 2 -1,103.93 -21.82 -99,956.60
- 3 -1,103.69 -22.06 -99,934.54
- 4 -1,103.44 -22.31 -99,912.23
- 5 -1,103.20 -22.55 -99,889.68
- Summary for 1996:
- Interest Paid: -5,518.43
- Principal Paid: -110.32
- Year Ending Balance: -99,889.68
- Sum of Interest Paid: -5,518.43
- Pmt# Interest Principal Balance
- 6 -1,102.95 -22.80 -99,866.88
- 7 -1,102.70 -23.05 -99,843.83
- 8 -1,102.44 -23.31 -99,820.52
- 9 -1,102.18 -23.57 -99,796.95
- 10 -1,101.92 -23.83 -99,773.12
- 11 -1,101.66 -24.09 -99,749.03
- 12 -1,101.40 -24.35 -99,724.68
- 13 -1,101.13 -24.62 -99,700.06
- 14 -1,100.85 -24.90 -99,675.16
- 15 -1,100.58 -25.17 -99,649.99
- 16 -1,100.30 -25.45 -99,624.54
- 17 -1,100.02 -25.73 -99,598.81
- Summary for 1997:
- Interest Paid: -13,218.13
- Principal Paid: -290.87
- Year Ending Balance: -99,598.81
- Sum of Interest Paid: -18,736.56
- Pmt# Interest Principal Balance
- 18 -1,099.74 -26.01 -99,572.80
- 19 -1,099.45 -26.30 -99,546.50
- .
- .
- .
- 346 -171.99 -953.76 -14,622.84
- 347 -161.46 -964.29 -13,658.55
- 348 -150.81 -974.94 -12,683.61
- 349 -140.05 -985.70 -11,697.91
- 350 -129.16 -996.59 -10,701.32
- 351 -118.16 -1,007.59 -9,693.73
- 352 -107.03 -1,018.72 -8,675.01
- 353 -95.79 -1,029.96 -7,645.05
- Summary for 2025:
- Interest Paid: -1,865.45
- Principal Paid: -11,643.55
- Year Ending Balance: -7,645.05
- Sum of Interest Paid: -305,034.80
- Pmt# Interest Principal Balance
- 354 -84.41 -1,041.34 -6,603.71
- 355 -72.92 -1,052.83 -5,550.88
- 356 -61.29 -1,064.46 -4,486.42
- 357 -49.54 -1,076.21 -3,410.21
- 358 -37.65 -1,088.10 -2,322.11
- 359 -25.64 -1,100.11 -1,222.00
- Final Payment (360): -1,235.49
- 360 -13.49 -1,222.00 0.00
- Summary for 2026:
- Interest Paid: -344.94
- Principal Paid: -7,645.05
-
- Total Interest: -305,379.74
-</pre>
-
-<p>The complete amortization table can be viewed in the
-<A HREF="./amortp.html#AmortPer">Periodic Amortization Schedule</A> for this loan.
-
-<p>You will notice several differences between this amortization schedule and the
-Annual Summary Schedule. The Periodic Payment Schedule lists the interest paid for
-each payment as well as the principal paid and the remaining balance to be repaid.
-At the end of each year an annual summary is printed. At the end of the table the
-total interest is printed as in the Annual Summary Schedule.
-
-<p>You will notice that the total interest output at the end of the Periodic Payment
-Schedule differs slightly from the total interest output at the end of the Annual Summary
-Schedule:
-
-<p>Total Interest for Periodic Payment Schedule:
-<pre>
- Total Interest: -305,379.74
-</pre>
-
-<p>Total Interest for Annual Summary Schedule:
-
-<pre>
- Total Interest: -305,378.87
-</pre>
-
-<p>The difference in total interest is due to the rounding of all quantities at
-each periodic payment. The Total Interest paid shown in the Periodic Payment
-Schedule will be the more accurate since all quantities exchanged in a financial
-transaction will be done to the nearest cent.
-
-<a name="AS_VarAdvPmt">
-<h2>Conventional Mortgage Schedule - Variable Advanced Payments</h2></a>
-<p>Conventional Mortgage Schedule - Variable Advanced Payments
-<p>Again using the loan in the previous examples, compute the amortization table using
-the advanced payment
-option to prepay the loan. As in the previous example, ignore any increase in the PV due to the
-delayed IP.
-
-<pre>
-<a>
- Effective Date: Thu Jun 06 00:00:00 1996
- Initial Payment Date: Thu Aug 01 00:00:00 1996
- The amortization options are:
- The Old Present Value (pv) was: 100,000.00
- The Old Periodic Payment (pmt) was: -1,125.75
- The Old Future Value (fv) was: 0.00
- 1: Amortize with Original Transaction Values
- and final payment: -1,234.62
-
- The New Present Value (pve) is: 100,919.30
- The New Periodic Payment (pmt) is: -1,136.12
- 2: Amortize with Original Periodic Payment
- and final payment: -49,132.55
- 3: Amortize with New Periodic Payment
- and final payment: -1,148.90
- 4: Amortize with Original Periodic Payment,
- new number of total payments (n): 417
- and final payment: -2,199.14
-
- Enter choice 1, 2, 3 or 4: <>
-</pre>
-
-<p>Press 1 for option 1:
-
-<pre>
- Amortization Schedule:
- Yearly, y, per Payment, p, or Advanced Payment, a, Amortization
- Enter choice y, p or a:
- <>
-</pre>
-
-<p>Press a for the Advanced Payment Option:
-
-<pre>
- Enter Filename for Amortization Schedule.
- (null string uses Standard Output):
-</pre>
-
-<p>Press enter to display output on screen:
-
-<pre>
- Amortization Table
- Effective Date: Thu Jun 06 00:00:00 1996
- Initial Payment Date: Thu Aug 01 00:00:00 1996
- Compounding Frequency per year: 12
- Payment Frequency per year: 12
- Compounding: Discrete
- Payments: End of Period
- Payments (359): -1,125.75
- Final payment (# 360): -1,234.62
- Nominal Annual Interest Rate: 13.25
- Effective Interest Rate Per Payment Period: 0.0110417
- Present Value: 100,000.00
- Advanced Prepayment Amortization
- Pmt# Interest Principal Prepay Total Pmt Balance
- 1 -1,104.17 -21.58 -21.82 -1,147.57 -99,956.60
- 2 -1,103.69 -22.06 -22.31 -1,148.06 -99,912.23
- 3 -1,103.20 -22.55 -22.80 -1,148.55 -99,866.88
- 4 -1,102.70 -23.05 -23.31 -1,149.06 -99,820.52
- 5 -1,102.18 -23.57 -23.83 -1,149.58 -99,773.12
- Summary for 1996:
- Interest Paid: -5,515.94
- Principal Paid: -226.88
- Year Ending Balance: -99,773.12
- Sum of Interest Paid: -5,515.94
- Pmt# Interest Principal Prepay Total Pmt Balance
- 6 -1,101.66 -24.09 -24.35 -1,150.10 -99,724.68
- 7 -1,101.13 -24.62 -24.90 -1,150.65 -99,675.16
- 8 -1,100.58 -25.17 -25.45 -1,151.20 -99,624.54
- 9 -1,100.02 -25.73 -26.01 -1,151.76 -99,572.80
- 10 -1,099.45 -26.30 -26.59 -1,152.34 -99,519.91
- 11 -1,098.87 -26.88 -27.18 -1,152.93 -99,465.85
- 12 -1,098.27 -27.48 -27.78 -1,153.53 -99,410.59
- 13 -1,097.66 -28.09 -28.40 -1,154.15 -99,354.10
- 14 -1,097.03 -28.72 -29.03 -1,154.78 -99,296.35
- 15 -1,096.40 -29.35 -29.68 -1,155.43 -99,237.32
- 16 -1,095.75 -30.00 -30.34 -1,156.09 -99,176.98
- 17 -1,095.08 -30.67 -31.01 -1,156.76 -99,115.30
- Summary for 1997:
- Interest Paid: -13,181.90
- Principal Paid: -657.82
- Year Ending Balance: -99,115.30
- Sum of Interest Paid: -18,697.84
- Pmt# Interest Principal Prepay Total Pmt Balance
- 18 -1,094.40 -31.35 -31.70 -1,157.45 -99,052.25
- 19 -1,093.70 -32.05 -32.40 -1,158.15 -98,987.80
- 20 -1,092.99 -32.76 -33.12 -1,158.87 -98,921.92
- .
- .
- .
- 167 -298.87 -826.88 -836.01 -1,961.76 -25,404.90
- 168 -280.51 -845.24 -854.57 -1,980.32 -23,705.09
- 169 -261.74 -864.01 -873.55 -1,999.30 -21,967.53
- 170 -242.56 -883.19 -892.94 -2,018.69 -20,191.40
- 171 -222.95 -902.80 -912.77 -2,038.52 -18,375.83
- 172 -202.90 -922.85 -933.04 -2,058.79 -16,519.94
- 173 -182.41 -943.34 -953.76 -2,079.51 -14,622.84
- Summary for 2010:
- Interest Paid: -3,448.07
- Principal Paid: -20,232.96
- Year Ending Balance: -14,622.84
- Sum of Interest Paid: -152,300.57
- Pmt# Interest Principal Prepay Total Pmt Balance
- 174 -161.46 -964.29 -974.94 -2,100.69 -12,683.61
- 175 -140.05 -985.70 -996.59 -2,122.34 -10,701.32
- 176 -118.16 -1,007.59 -1,018.72 -2,144.47 -8,675.01
- 177 -95.79 -1,029.96 -1,041.34 -2,167.09 -6,603.71
- 178 -72.92 -1,052.83 -1,064.46 -2,190.21 -4,486.42
- 179 -49.54 -1,076.21 -1,088.10 -2,213.85 -2,322.11
- 180 -25.64 -1,100.11 -1,222.00 -2,347.75 0.00
- Summary for 2011:
- Interest Paid: -663.56
- Principal Paid: -14,622.84
-
- Total Interest: -152,964.13
-</pre>
-
-<p>The complete amortization table can be viewed in the
-<A HREF="./amorta.html#AmortAdv">Advanced Payment Amortization Schedule</A> for this loan.
-
-<p>This schedule has added two columns over the Periodic Payment Schedule in Example 7. Namely,
-<tt>Prepay</tt> and the <tt>Total Pmt</tt> columns. The <tt>Prepay</tt> column is the
-amount of the loan prepayment for the period. The <tt>Total Pmt</tt> column is the sum
-of the periodic payment and the Prepayment. Note that both the <tt>Prepay</tt> and the
-<tt>Total Pmt</tt> quantities increase with each period.
-
-<a name="AS_ConstAdvPmt">
-<h2>Conventional Mortgage Schedule - Constant Advanced Payments</h2></a>
-<p>Conventional Mortgage Schedule - Constant Advanced Payments
-<p>Using the loan in the previous examples, compute the amortization table using
-another payment option for repaying a loan ahead of schedule and reducing the interest
-paid, constant repayments at each periodic payment. Suppose a constant $100.00 is paid
-towards the principal with each periodic payment. How many payments are needed to fully payoff
-the loan and what is the total interest paid?
-
-<p>As in the previous example, ignore any increase in the PV due to the
-delayed IP.
-
-<p>There are two ways to compute the amortization table for this type of prepayment option.
-In the first method, set the variable 'FP' to the amount of the monthly prepayment.
-
-<pre>
-<>FP=-100
- -100
-<>a
- Effective Date: Thu Jun 06 00:00:00 1996
- Initial Payment Date: Thu Aug 01 00:00:00 1996
- The amortization options are:
- The Old Present Value (pv) was: 100,000.00
- The Old Periodic Payment (pmt) was: -1,125.75
- The Old Future Value (fv) was: 0.00
- 1: Amortize with Original Transaction Values
- and final payment: -1,234.62
-
- The New Present Value (pve) is: 100,919.30
- The New Periodic Payment (pmt) is: -1,136.12
- 2: Amortize with Original Periodic Payment
- and final payment: -49,132.55
- 3: Amortize with New Periodic Payment
- and final payment: -1,148.90
- 4: Amortize with Original Periodic Payment,
- new number of total payments (n): 417
- and final payment: -2,199.14
-
- Enter choice 1, 2, 3 or 4: <>
-</pre>
-
-<p>Press 1 for option 1:
-
-<pre>
- Amortization Schedule:
- Yearly, y, per Payment, p, Advanced Payment, a, or Fixed Prepayment, f, Amortization
- Enter choice y, p, a or f:
- <>
-</pre>
-
-<p>Press f for the Fixed Prepayment schedule.
-
-<pre>
- Enter Filename for Amortization Schedule.
- (null string uses Standard Output):
-</pre>
-
-<p>Press enter to display output on screen:
-
-<pre>
-Amortization Table
-Effective Date: Thu Jun 6 00:00:00 1996
-Initial Payment Date: Thu Aug 1 00:00:00 1996
-Compounding Frequency per year: 12
-Payment Frequency per year: 12
-Compounding: Discrete
-Payments: End of Period
-Payments (359): -1,125.75
-Final payment (# 360): -1,234.62
-Nominal Annual Interest Rate: 13.25
- Effective Interest Rate Per Payment Period: 0.0110417
-Present Value: 100,000.00
-Advanced Prepayment Amortization - fixed prepayment: -100.00
-Pmt# Interest Principal Prepay Total Pmt Balance
- 1 -1,104.17 -21.58 -100.00 -1,225.75 -99,878.42
- 2 -1,102.82 -22.93 -100.00 -1,225.75 -99,755.49
- 3 -1,101.47 -24.28 -100.00 -1,225.75 -99,631.21
- 4 -1,100.09 -25.66 -100.00 -1,225.75 -99,505.55
- 5 -1,098.71 -27.04 -100.00 -1,225.75 -99,378.51
-Summary for 1996:
- Interest Paid: -5,507.26
- Principal Paid: -621.49
- Year Ending Balance: -99,378.51
- Sum of Interest Paid: -5,507.26
-Pmt# Interest Principal Prepay Total Pmt Balance
- 6 -1,097.30 -28.45 -100.00 -1,225.75 -99,250.06
- 7 -1,095.89 -29.86 -100.00 -1,225.75 -99,120.20
- 8 -1,094.45 -31.30 -100.00 -1,225.75 -98,988.90
- 9 -1,093.00 -32.75 -100.00 -1,225.75 -98,856.15
- 10 -1,091.54 -34.21 -100.00 -1,225.75 -98,721.94
- 11 -1,090.05 -35.70 -100.00 -1,225.75 -98,586.24
- 12 -1,088.56 -37.19 -100.00 -1,225.75 -98,449.05
- 13 -1,087.04 -38.71 -100.00 -1,225.75 -98,310.34
- 14 -1,085.51 -40.24 -100.00 -1,225.75 -98,170.10
- 15 -1,083.96 -41.79 -100.00 -1,225.75 -98,028.31
- 16 -1,082.40 -43.35 -100.00 -1,225.75 -97,884.96
- 17 -1,080.81 -44.94 -100.00 -1,225.75 -97,740.02
-Summary for 1997:
- Interest Paid: -13,070.51
- Principal Paid: -1,638.49
- Year Ending Balance: -97,740.02
- Sum of Interest Paid: -18,577.77
-.
-.
-.
-
-Pmt# Interest Principal Prepay Total Pmt Balance
- 186 -298.60 -827.15 -100.00 -1,225.75 -26,115.84
- 187 -288.36 -837.39 -100.00 -1,225.75 -25,178.45
- 188 -278.01 -847.74 -100.00 -1,225.75 -24,230.71
- 189 -267.55 -858.20 -100.00 -1,225.75 -23,272.51
- 190 -256.97 -868.78 -100.00 -1,225.75 -22,303.73
- 191 -246.27 -879.48 -100.00 -1,225.75 -21,324.25
- 192 -235.46 -890.29 -100.00 -1,225.75 -20,333.96
- 193 -224.52 -901.23 -100.00 -1,225.75 -19,332.73
- 194 -213.47 -912.28 -100.00 -1,225.75 -18,320.45
- 195 -202.29 -923.46 -100.00 -1,225.75 -17,296.99
- 196 -190.99 -934.76 -100.00 -1,225.75 -16,262.23
- 197 -179.56 -946.19 -100.00 -1,225.75 -15,216.04
-Summary for 2012:
- Interest Paid: -2,882.05
- Principal Paid: -11,826.95
- Year Ending Balance: -15,216.04
- Sum of Interest Paid: -156,688.79
-Pmt# Interest Principal Prepay Total Pmt Balance
- 198 -168.01 -957.74 -100.00 -1,225.75 -14,158.30
- 199 -156.33 -969.42 -100.00 -1,225.75 -13,088.88
- 200 -144.52 -981.23 -100.00 -1,225.75 -12,007.65
- 201 -132.58 -993.17 -100.00 -1,225.75 -10,914.48
- 202 -120.51 -1,005.24 -100.00 -1,225.75 -9,809.24
- 203 -108.31 -1,017.44 -100.00 -1,225.75 -8,691.80
- 204 -95.97 -1,029.78 -100.00 -1,225.75 -7,562.02
- 205 -83.50 -1,042.25 -100.00 -1,225.75 -6,419.77
- 206 -70.88 -1,054.87 -100.00 -1,225.75 -5,264.90
- 207 -58.13 -1,067.62 -100.00 -1,225.75 -4,097.28
- 208 -45.24 -1,080.51 -100.00 -1,225.75 -2,916.77
- 209 -32.21 -1,093.54 -100.00 -1,225.75 -1,723.23
-Summary for 2013:
- Interest Paid: -1,216.19
- Principal Paid: -13,492.81
- Year Ending Balance: -1,723.23
- Sum of Interest Paid: -157,904.98
-Pmt# Interest Principal Prepay Total Pmt Balance
- 210 -19.03 -1,106.72 -100.00 -1,225.75 -516.51
- 211 -5.70 -516.51 0.00 -522.21 0.00
-
-Total Interest: 157,929.71
-
-</pre>
-
-<p>In the second method, the periodic payment is increased by 100. With this method,
-the annual summary table can also be computed.
-
-<pre>
-<>s
-Financial Calculator
-Copyright (C) 1990 - 1997 Terry D. Boldt, All Rights Reserved.
-Current Financial Calculator Status:
-Compounding Frequency: (CF) 12
-Payment Frequency: (PF) 12
-Compounding: Discrete (disc = TRUE)
-Payments: End of Period (bep = FALSE)
-Number of Payment Periods (n): 360 (Years: 30)
-Nominal Annual Interest Rate (i): 13.25
- Effective Interest Rate Per Payment Period: 0.0110417
-Present Value (pv): 100,000.00
-Periodic Payment (pmt): -1,125.75
-Future Value (fv): 0.00
-Effective Date: Thu Jun 06 00:00:00 1996(2450241)
-Initial Payment Date: Thu Aug 01 00:00:00 1996(2450297)
-<>pmt-=100
- -1,225.75
-<>N
- 210.42
-<>
-</pre>
-
-<p>Thus, the loan will now be fully repaid in 210 full payments and a partial payment
-as illustrated in the previous table.
-To get the total interest paid, display the Annual Summary Amortization Schedule:
-
-<pre>
-Effective Date: Thu Jun 06 00:00:00 1996
-Initial Payment Date: Thu Aug 01 00:00:00 1996
-The amortization options are:
-The Old Present Value (pv) was: 100,000.00
-The Old Periodic Payment (pmt) was: -1,225.75
-The Old Future Value (fv) was: 0.00
-1: Amortize with Original Transaction Values
- and final payment: -1,742.55
-
-The New Present Value (pve) is: 100,919.30
-The New Periodic Payment (pmt) is: -1,237.02
-2: Amortize with Original Periodic Payment
- and final payment: -10,967.39
-3: Amortize with New Periodic Payment
- and final payment: -1,757.20
-4: Amortize with Original Periodic Payment,
- new number of total payments (n): 218
- and final payment: -1,668.45
-
-Enter choice 1, 2, 3 or 4: <>
-</pre>
-
-<p>Press '1' for option 1:
-
-<pre>
- Amortization Schedule:
-Yearly, y, per Payment, p, or Advanced Payment, a, Amortization
-Enter choice y, p or a:
-<>
-</pre>
-
-<p>Press 'y' for an annual Summary
-
-<pre>
-Enter Filename for Amortization Schedule.
- (null string uses Standard Output):
-</pre>
-
-<p>Press enter to display the summary on the screen:
-
-<pre>
- Amortization Table
- Effective Date: Thu Jun 06 00:00:00 1996
- Initial Payment Date: Thu Aug 01 00:00:00 1996
- Compounding Frequency per year: 12
- Payment Frequency per year: 12
- Compounding: Discrete
- Payments: End of Period
- Payments (209): -1,225.75
- Final payment (# 210): -1,742.55
- Nominal Annual Interest Rate: 13.25
- Effective Interest Rate Per Payment Period: 0.0110417
- Present Value: 100,000.00
- Year Interest Ending Balance
- 1996 -5,507.26 -99,378.51
- 1997 -13,070.52 -97,740.03
- 1998 -12,839.74 -95,870.77
- 1999 -12,576.45 -93,738.22
- 2000 -12,276.08 -91,305.30
- 2001 -11,933.40 -88,529.70
- 2002 -11,542.46 -85,363.16
- 2003 -11,096.45 -81,750.61
- 2004 -10,587.62 -77,629.23
- 2005 -10,007.12 -72,927.35
- 2006 -9,344.86 -67,563.21
- 2007 -8,589.32 -61,443.53
- 2008 -7,727.36 -54,461.89
- 2009 -6,744.00 -46,496.89
- 2010 -5,622.13 -37,410.02
- 2011 -4,342.24 -27,043.26
- 2012 -2,882.08 -15,216.34
- 2013 -1,216.25 -1,723.59
- 2014 -18.96 0.00
-
- Total Interest: -157,924.30
-</pre>
-
-<p>From the last line the Total interest has been decreased from $305,379.74 to
-$157,924.30.
-
-<p>We can also ask how much of a constant repayment would be necessary to fully
-repay the loan in 15 years and what would be the total interest paid?
-
-<pre>
- <>n=12*15
- 180
- <>opmt=pmt
- -1,125.75
- <>PMT
- -1,281.74
- <>pmt-opmt
- -155.99
-</pre>
-
-<p>Thus, a constant advanced repayment per periodic payment of $155.99 would fully
-amortize the loan in 15 years.
-
-<pre>
- <>a
- Effective Date: Thu Jun 06 00:00:00 1996
- Initial Payment Date: Thu Aug 01 00:00:00 1996
- The amortization options are:
- The Old Present Value (pv) was: 100,000.00
- The Old Periodic Payment (pmt) was: -1,281.74
- The Old Future Value (fv) was: 0.00
- 1: Amortize with Original Transaction Values
- and final payment: -1,279.73
-
- The New Present Value (pve) is: 100,919.30
- The New Periodic Payment (pmt) is: -1,293.52
- 2: Amortize with Original Periodic Payment
- and final payment: -7,915.43
- 3: Amortize with New Periodic Payment
- and final payment: -1,293.20
- 4: Amortize with Original Periodic Payment,
- new number of total payments (n): 185
- and final payment: -1,738.05
-
- Enter choice 1, 2, 3 or 4: <>
-</pre>
-
-<p>Press '1' for option 1:
-
-<pre>
- Amortization Schedule:
- Yearly, y, per Payment, p, or Advanced Payment, a, Amortization
- Enter choice y, p or a:
- <>
-</pre>
-
-<p>Press 'y' for an annual Summary
-
-<pre>
- Amortization Table
- Effective Date: Thu Jun 06 00:00:00 1996
- Initial Payment Date: Thu Aug 01 00:00:00 1996
- Compounding Frequency per year: 12
- Payment Frequency per year: 12
- Compounding: Discrete
- Payments: End of Period
- Payments (179): -1,281.74
- Final payment (# 180): -1,279.73
- Nominal Annual Interest Rate: 13.25
- Effective Interest Rate Per Payment Period: 0.0110417
- Present Value: 100,000.00
- Year Interest Ending Balance
- 1996 -5,501.01 -99,092.31
- 1997 -12,987.86 -96,699.29
- 1998 -12,650.80 -93,969.21
- 1999 -12,266.27 -90,854.60
- 2000 -11,827.58 -87,301.30
- 2001 -11,327.09 -83,247.51
- 2002 -10,756.12 -78,622.75
- 2003 -10,104.72 -73,346.59
- 2004 -9,361.57 -67,327.28
- 2005 -8,513.75 -60,460.15
- 2006 -7,546.51 -52,625.78
- 2007 -6,443.04 -43,687.94
- 2008 -5,184.14 -33,491.20
- 2009 -3,747.93 -21,858.25
- 2010 -2,109.42 -8,586.79
- 2011 -383.38 0.00
-
- Total Interest: -130,711.19
-</pre>
-
-<p>The toral interest is reduced to $130,711.19. This compares to:
-
-<ol>
-<li>$130,711.19 - Fixed prepayment $155.99/period, 15 year term
-<li>$152,964.13 - Variable Advanced Repayment, 15 year term
-<li>$305,379.74 - no prepayment, 30 year term
-</ol>
-
-<a name="BalloonPmt">
-<h2>Balloon Payment</h2></a>
-<p>Balloon Payment
-<p>On long term loans, small changes in the periodic payments can generate
-large changes in the future value. If the monthly payment in the previous example is
-rounded down to $1125, how much additional (balloon) payment will be due
-with the final regular payment.
-<pre>
- <>s
- Financial Calculator
- Copyright (C) 1990 - 1997 Terry D. Boldt, All Rights Reserved.
- Current Financial Calculator Status:
- Compounding Frequency: (CF) 12
- Payment Frequency: (PF) 12
- Compounding: Discrete (disc = TRUE)
- Payments: End of Period (bep = FALSE)
- Number of Payment Periods (n): 180 (Years: 15)
- Nominal Annual Interest Rate (i): 13.25
- Effective Interest Rate Per Payment Period: 0.0110417
- Present Value (pv): 100,000.00
- Periodic Payment (pmt): -1,281.74
- Future Value (fv): 0.00
- Effective Date: Thu Jun 06 00:00:00 1996(2450241)
- Initial Payment Date: Thu Aug 01 00:00:00 1996(2450297)
- <>n=360
- 360
- <>pmt=-1125
- -1,125
- <>FV
- -3,579.99
- <>
-</pre>
-
-<a name="CanadianMortg">
-<h2>Canadian Mortgage</h2></a>
-<p>Canadian Mortgage
-<p>A "Canadian Mortgage" is defined with semi-annual compunding, <tt>CF == 2</tt>,
-and monthly payments, <tt>PF == 12</tt>.
-
-<p>Find the monthly end-of-period payment necessary to fully amortize a 25 year
-$85,000 loan at 11% compounded semi-annually.
-<pre>
- <>d
- <>CF=2
- 2
- <>n=300
- 300
- <>i=11
- 11
- <>pv=85000
- 85,000
- <>PMT
- -818.15
-</pre>
-
-<a name="EuropeanMortg">
-<h2></h2></a>
-<p>European Mortgage
-<p>The "effective annual rate (EAR)" is used in some countries (especially
- in Europe) in lieu of the nominal rate commonly used in the United States
- and Canada. For a 30 year $90,000 mortgage at 14% (EAR), compute the monthly
- end-of-period payments. When using an EAR, the compounding frequency is
- set to 1.
-<pre>
- <>d
- <>CF=1
- 1
- <>n=30*12
- 360
- <>i=14
- 14
- <>pv=90000
- 90,000
- <>PMT
- -1,007.88
-</pre>
-
-<a name="BiWeeklySav">
-<h2>Bi-weekly Savings</h2></a>
-<p>Bi-weekly Savings
-<p>Compute the future value, fv, of bi-weekly savings of $100 for 3 years at a
- nominal annual rate of 5.5% compounded daily. (Set payment to
- beginning-of-period, bep = TRUE)
-<pre>
- <>d
- <>bep=TRUE
- 1
- <>CF=365
- 365
- <>PF=26
- 26
- <>n=3*26
- 78
- <>i=5.5
- 5.50
- <>pmt=-100
- -100
- <>FV
- 8,489.32
-</pre>
-
-<a name="PV_AnnuiytDue">
-<h2>Present Value - Annuity Due</h2></a>
-<p>Present Value - Annuity Due
-<p>What is the present value of $500 to be received at the beginning of each
- quarter over a 10 year period if money is being discounted at 10% nominal
- annual rate compounded monthly?
-<pre>
- <>d
- <>bep=TRUE
- 1
- <>PF=4
- 4
- <>n=4*10
- 40
- <>i=10
- 10
- <>pmt=500
- 500
- <>PV
- -12,822.64
-</pre>
-
-<a name="EffRate">
-<h2>Effective Rate - 365/360 Basis</h2></a>
-<p>Effective Rate - 365/360 Basis
-<p>Compute the effective annual rate (%APR) for a nominal annual rate of 12%
- compounded on a 365/360 basis used by some Savings & Loan Associations.
-<pre>
- <>d
- <>n=365
- 365
- <>CF=365
- 365
- <>PF=360
- 360
- <>i=12
- 12
- <>pv=-100
- -100
- <>FV
- 112.94
- <>fv+pv
- 12.94
-</pre>
-
-<a name="EffAPY">
-<h2>Certificate of Deposit, Annual Percentage Yield</h2></a>
-<p>Certificate of Deposit, Annual Percentage Yield
-<p>Most, if not all banks have started stating return rates on Certificates of Deposit, CDs, as
-an Annual Percentage Yoild, APY, and the nominal annual interest. For example, a bank will advertise
-a CD with a 18 month term, an APY of 5.20% and a nominal rate of 5.00. What values of CF and PF will
-are being used?
-
-<pre>
- <>d
- <>n=365
- 365
- <>CF=PF=365
- 365
- <>i=5
- 5
- <>pv=-100
- -100
- <>FV
- 105.13
- <>CF=PF=360
- 360
- <>fv+pv
- -5.20
-</pre>
-<a name="MortgPoints">
-<h2>Mortgage with "Points"</h2></a>
-<p>Mortgage with "Points"
-<p>What is the true APR of a 30 year, $75,000 loan at a nominal rate of 13.25%
- compounded monthly, with monthly end-of-period payments, if 3 "points"
- are charged? The pv must be reduced by the dollar value of the points
- and/or any lenders fees to establish an effective pv. Because payments remain
- the same, the true APR will be higher than the nominal rate. Note, first
- compute the payments on the pv of the loan amount.
-<pre>
- <>n=30*12
- 360
- <>i=13.25
- 13.25
- <>pv=75000
- 75,000
- <>PMT
- -844.33
- <>pv-=pv*0.03
- 72,750.00
- <>I
- 13.69
- <>
-</pre>
-
-<a name="EquivPmt">
-<h2>Equivalent Payments</h2></a>
-<p>Equivalent Payments
-<p>Find the equivalent monthly payment required to amortize a 20 year $40,000
-loan at 10.5% nominal annual rate compounded monthly, with 10 annual
-payments of $5029.71 remaining. Compute the pv of the remaining annual
-payments, then change n, the number of periods, and the payment frequency,
-PF, to a monthly basis and compute the equivalent monthly pmt.
-<pre>
- <>d
- <>PF=1
- 1
- <>n=10
- 10
- <>i=10.5
- 10.50
- <>pmt=-5029.71
- -5,029.71
- <>PV
- 29,595.88
- <>PF=12
- 12
- <>n=120
- 120
- <>PMT
- -399.35
-</pre>
-
-<a name="Perpetuity">
-<h2>Perpetuity - Continuous Compounding</h2></a>
-<p>Perpetuity - Continuous Compounding
-<p>If you can purchase a single payment annuity with an initial investment of
- $60,000 that will be invested at 15% nominal annual rate compounded
- continuously, what is the maximum monthly return you can receive without
- reducing the $60,000 principal? If the principal is not disturbed, the
- payments can go on indefinitely (a perpetuity). Note that the term,n, of
- a perpetuity is immaterial. It can be any non-zero value.
-<pre>
- <>d
- <>disc=FALSE
- 0
- <>n=12
- 12
- <>CF=1
- 1
- <>i=15
- 15
- <>fv=60000
- 60,000
- <>pv=-60000
- -60,000
- <>PMT
- 754.71
-</pre>
-
-<a name="DevCo">
-<h2>Investment Return</h2></a>
-<p>Investment Return
-<p>A development company is purchasing an investment property with an annual net cash
-flow of $25,000.00. The expected holding period for the property is 10 years with an estimated
-selling price of $850,000.00 at that time. If the company is to realize a 15% yield on the
-investment, what is the maximum price they can pay for the property today?
-
-<pre>
- Financial Calculator
- Copyright (C) 1990 - 1997 Terry D. Boldt, All Rights Reserved.
- <>CF=PF=1
- 1
- <>n=10
- 10
- <>i=15
- 15
- <>pmt=25000
- 25,000
- <>fv=850000
- 850,000
- <>PV
- -335,576.22
-</pre>
-
-<p>So the maximum purchase price today would be $335,576.22 to achieve the desired yield.
-
-<a name="Retiement">
-<h2>Retirement Investment</h2></a>
-<p>Retirement Investment
-<p>You wish to retire in 20 years and wish to deposit a lump sum amount in an account
-today which will grow to $100,000.00, earning 6.5% interest compounded semi-annually.
-How much do you need to deposit?
-
-<pre>
- Financial Calculator
- Copyright (C) 1990 - 1997 Terry D. Boldt, All Rights Reserved.
- <>CF=PF=2
- 2
- <>n=2*20
- 40
- <>i=6.5
- 6.50
- <>fv=100000
- 100,000
- <>PV
- -27,822.59
-</pre>
-
-<p>If you were to make semi-annual deposits of $600.00, how much would you need to deposit today?
-
-<pre>
- <>pmt=-600
- -600
- <>PV
- -14,497.53
-</pre>
-
-<p>If you were to make monthly deposits of $100.00?
-
-<pre>
- <>PF=12
- 12
- <>n=20*12
- 240
- <>pmt=-100
- -100
- <>PV
- -14,318.21
-</pre>
-
-<a name="PropVal">
-<h2>Property Values</h2></a>
-<p>Property Values
-<p>Property values in an area you are considering moving to are declining at the rate
-of 2.35% annually. What will property presently appraised at $155,500.00 be worth in 10 years
-if the trend continues?
-
-<pre>
- Financial Calculator
- Copyright (C) 1990 - 1997 Terry D. Boldt, All Rights Reserved.
- <>CF=PF=1
- 1
- <>n=10
- 10
- <>i=-2.35
- -2.35
- <>pv=155500
- 155,500
- <>FV
- -122,589.39
-</pre>
-
-<a name="CollegeExpenses">
-<h2>College Expenses</h2></a>
-<p>College Expenses
-<p>You and your spouse are planning for your child's college expenses. Your child
-will be entering college in 15 years. You expect that college expenses at that time
-will amount to $25,000.00 per year or about $2,100.00/month. If the child withdrew
-the expenses from a bank account monthly paying 6% compounded on a daily basis (using
-360 days/year), how much must you deposit in the account at the start of the four
-years?
-
-<pre>
- Financial Calculator
- Copyright (C) 1990 - 1997 Terry D. Boldt, All Rights Reserved.
- <>CF=360
- 360
- <>PF=12
- 12
- <>n=12*4
- 48
- <>i=6
- 6
- <>pmt=2100
- 2,100
- <>PV
- -89,393.32
-</pre>
-
-<p>Your next problem is how to accumulate the money by the time the child starts college.
-You have a $50,000.00 paid-up insurance policy for your child that has a cash value
-of $6,500.00. It is accumulating annual dividends of $1,200 earning 6.75% compounded monthly.
-What will be the cash value of the policy in 15 years?
-
-<pre>
- <>college_fund=-pv
- 89,393.32
- <>d
- <>PF=1
- 1
- <>n=20
- 20
- <>i=6.75
- 6.75
- <>pmt=1200
- 1,200
- <>FV
- -48,995.19
- <>insurance=-fv+6500
- 55,495.19
- <>college_fund-insurance
- 33,898.13
-</pre>
-
-<p>The paid-up insurance cash value and dividends will provide $55,495.19 of the amount
-necessary, leaving $33,898.13 to accumulate in savings. Making monthly payments into
-a savings account paying 4.5% compounded daily, what level of monthly payments would be
-needed?
-
-<pre>
- Financial Calculator
- Copyright (C) 1990 - 1997 Terry D. Boldt, All Rights Reserved.
- <>d
- <>CF=360
- 360
- <>n=PF*15
- 180
- <>i=4.5
- 4.50
- <>fv=college_fund - insurance
- 33,898.13
- <>PMT
- -132.11
-</pre>
-
-<a name="refs">
-<h1>References</h1></a>
-<address>
-PPC ROM User's Manual
-<br>pages 148 - 164
-</address>
-<HR size=4>
-<A HREF="#TOP">TOP</A>
-</body>
\ No newline at end of file
commit 387b4988e523e9438b54e97d1cecb7bc720207ce
Author: Geert Janssens <geert at kobaltwit.be>
Date: Thu May 23 12:29:16 2024 +0200
Move doxygen target and related files to toplevel.
Note: this also means the target directory changes from
libgnucash/docs/html
to
[toplevel]/doxygen/html
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 73f0c179df..33119ac3bd 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -843,6 +843,13 @@ add_definitions (-DHAVE_CONFIG_H)
set (CONFIG_H ${CMAKE_CURRENT_BINARY_DIR}/common/config.h)
configure_file (${CMAKE_CURRENT_SOURCE_DIR}/common/config.h.cmake.in ${CONFIG_H})
+# The doxygen developer documentation
+find_program(DOXYGEN doxygen)
+if (NOT ${DOXYGEN} STREQUAL "DOXYGEN-NOTFOUND")
+ configure_file(doxygen.cfg.in doxygen.cfg)
+ add_custom_target(doc ${DOXYGEN} doxygen.cfg)
+endif()
+
# The subdirectories
add_subdirectory (borrowed)
add_subdirectory (data)
@@ -884,7 +891,10 @@ endif()
set(DIST_FILE "${PACKAGE_PREFIX}.tar")
set(toplvl_DIST_local ${gnucash_DOCS}
- CMakeLists.txt README)
+ doxygen.cfg.in
+ doxygen_main_page.c
+ CMakeLists.txt
+ README)
set_local_dist(toplvl_DIST ${toplvl_DIST_local})
diff --git a/libgnucash/doc/doxygen.cfg.in b/doxygen.cfg.in
similarity index 99%
rename from libgnucash/doc/doxygen.cfg.in
rename to doxygen.cfg.in
index 156f491d61..9b90630d61 100644
--- a/libgnucash/doc/doxygen.cfg.in
+++ b/doxygen.cfg.in
@@ -68,7 +68,7 @@ PROJECT_LOGO =
# entered, it will be relative to the location where doxygen was started. If
# left blank the current directory will be used.
-OUTPUT_DIRECTORY =
+OUTPUT_DIRECTORY = doxygen
# If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096
# sub-directories (in 2 levels) under the output directory of each output format
diff --git a/libgnucash/doc/doxygen_main_page.c b/doxygen_main_page.c
similarity index 100%
rename from libgnucash/doc/doxygen_main_page.c
rename to doxygen_main_page.c
diff --git a/libgnucash/doc/CMakeLists.txt b/libgnucash/doc/CMakeLists.txt
index 4129533416..f816f92d1b 100644
--- a/libgnucash/doc/CMakeLists.txt
+++ b/libgnucash/doc/CMakeLists.txt
@@ -1,7 +1,5 @@
set(doc_FILES
constderv.html
- doxygen.cfg.in
- doxygen_main_page.c
finderv.html
finutil.html
README
@@ -9,9 +7,3 @@ set(doc_FILES
set_local_dist(doc_DIST_local CMakeLists.txt ${doc_FILES})
set(doc_DIST ${doc_DIST_local} ${doc_design_DIST} PARENT_SCOPE)
-
-find_program(DOXYGEN doxygen)
-if (NOT ${DOXYGEN} STREQUAL "DOXYGEN-NOTFOUND")
- configure_file(doxygen.cfg.in doxygen.cfg)
- add_custom_target(doc ${DOXYGEN} doxygen.cfg)
-endif()
diff --git a/po/POTFILES.in b/po/POTFILES.in
index 9338bf7022..7b65ce41ce 100644
--- a/po/POTFILES.in
+++ b/po/POTFILES.in
@@ -621,7 +621,6 @@ libgnucash/core-utils/gnc-locale-utils.cpp
libgnucash/core-utils/gnc-path.c
libgnucash/core-utils/gnc-prefs.c
libgnucash/core-utils/gnc-version.c
-libgnucash/doc/doxygen_main_page.c
libgnucash/engine/Account.cpp
libgnucash/engine/cap-gains.cpp
libgnucash/engine/cashobjects.cpp
commit c816d2b34fec5760adad272ce4bd6c8596d0333c
Author: Geert Janssens <geert at kobaltwit.be>
Date: Thu May 23 12:10:35 2024 +0200
Doxygen - minor cleanup of gnc-lot.h
diff --git a/libgnucash/engine/gnc-lot.h b/libgnucash/engine/gnc-lot.h
index 9bb5d74c54..a2eff8b5ab 100644
--- a/libgnucash/engine/gnc-lot.h
+++ b/libgnucash/engine/gnc-lot.h
@@ -102,82 +102,92 @@ QofBook * gnc_lot_get_book (GNCLot *);
void gnc_lot_begin_edit (GNCLot *lot);
void gnc_lot_commit_edit (GNCLot *lot);
-/** The gnc_lot_add_split() routine adds a split to this lot. Note
- * that *all* splits in a lot must also be in the same account.
- * Note that this routine adds the split unconditionally, with
+/** Adds a split to this lot.
+ *
+ * @note
+ * - *All* splits in a lot must be in the same account.
+ * - Splits are added unconditionally, with
* no regard for the accounting policy. To enforce a particular
* accounting policy, use the xaccSplitAssignToLot() routine
* instead.
*/
void gnc_lot_add_split (GNCLot *, Split *);
+
+/** Adds a split from this lot.
+ */
void gnc_lot_remove_split (GNCLot *, Split *);
-/** The gnc_lot_get_split_list() routine returns a GList of all the
- * splits in this lot. Do *not* free this list when done;
- * it is a pointer straight into the lots internal list. Do
- * *not* add to or remove from this list directly. Calling
- * either gnc_lot_add_split() or gnc_lot_remove_split() will
- * invalidate the returned pointer.
+/** Returns a list of all the splits in this lot.
+ *
+ * @returns GList
+ *
+ * This GList is owned and managed by the lot.
+ * - Do *not* free it when done.
+ * - Do *not* modify it directly
+ * - Calls to either gnc_lot_add_split() or gnc_lot_remove_split()
+ * will invalidate the returned pointer
*/
SplitList * gnc_lot_get_split_list (const GNCLot *);
gint gnc_lot_count_splits (const GNCLot *);
-/** The gnc_lot_get_account() routine returns the account with which
- * this lot is associated. */
+/** Returns the account with which this lot is associated.
+ */
/*@ dependent @*/
Account * gnc_lot_get_account (const GNCLot *);
void gnc_lot_set_account(GNCLot*, Account*);
-/** The gnc_lot_get_cached_invoice() routine returns the invoice with
- * which this lot is associated. */
+/** Returns the invoice with which this lot is associated.
+ */
/*@ dependent @*/
GncInvoice * gnc_lot_get_cached_invoice (const GNCLot *lot);
void gnc_lot_set_cached_invoice(GNCLot* lot, GncInvoice *invoice);
-/** The gnc_lot_get_balance() routine returns the balance of the lot.
- * The commodity in which this balance is expressed is the commodity
- * of the account. */
+/** Returns the lot balance.
+ * This balance will be expressed in the lot account's commodity.
+ */
gnc_numeric gnc_lot_get_balance (GNCLot *);
-/** The gnc_lot_get_balance_before routine computes both the balance and
- * value in the lot considering only splits in transactions prior to the
- * one containing the given split or other splits in the same transaction.
+/** Computes both the balance and value in the lot considering only splits
+ * in transactions prior to the one containing the given split or other
+ * splits in the same transaction.
* The first return value is the amount and the second is the value. */
void gnc_lot_get_balance_before (const GNCLot *, const Split *,
gnc_numeric *, gnc_numeric *);
-/** The gnc_lot_is_closed() routine returns a boolean flag: is this
- * lot closed? A lot is closed if its balance is zero. This
- * routine is faster than using gnc_lot_get_balance() because
- * once the balance goes to zero, this fact is cached.
+/** Returns closed status of the given lot.
+ * A lot is closed if its balance is zero. This
+ * routine is faster than using gnc_lot_get_balance() because
+ * once the balance goes to zero, this fact is cached.
+ *
+ * @returns boolean
*/
gboolean gnc_lot_is_closed (GNCLot *);
-/** The gnc_lot_get_earliest_split() routine is a convenience routine
- * that helps identify the earliest date in the lot. It simply
- * loops over all of the splits in the lot, and returns the split
- * with the earliest split->transaction->date_posted. It may not
- * necessarily identify the lot opening split.
+/** Convenience routine to identify the earliest date in the lot.
+ * It loops over all of the splits in the lot, and returns the split
+ * with the earliest split->transaction->date_posted. It may not
+ * necessarily identify the lot opening split.
*/
Split * gnc_lot_get_earliest_split (GNCLot *lot);
-/** The gnc_lot_get_latest_split() routine is a convenience routine
- * that helps identify the date this lot was closed. It simply
- * loops over all of the splits in the lot, and returns the split
- * with the latest split->transaction->date_posted.
+/** Convenience routineto identify the date this lot was closed.
+ * It simply loops over all of the splits in the lot, and returns
+ * the split with the latest split->transaction->date_posted.
*/
Split * gnc_lot_get_latest_split (GNCLot *lot);
/** Reset closed flag so that it will be recalculated. */
void gnc_lot_set_closed_unknown(GNCLot*);
-/** Get and set the account title, or the account notes, or the marker. */
+/** @name Get/set the account title and notes.
+ @{ */
const char * gnc_lot_get_title (const GNCLot *);
const char * gnc_lot_get_notes (const GNCLot *);
void gnc_lot_set_title (GNCLot *, const char *);
void gnc_lot_set_notes (GNCLot *, const char *);
+/** @} */
-/** XXX: Document? */
+/** @todo Document this function ? */
GNCLot * gnc_lot_make_default (Account * acc);
#define gnc_lot_get_guid(X) qof_entity_get_guid(QOF_INSTANCE(X))
commit e8d72ad53f9853ef5699d27f5edde9401aa39a81
Author: Geert Janssens <geert at kobaltwit.be>
Date: Thu May 23 11:38:39 2024 +0200
Doxygen - merge separate txt files into respective header files
diff --git a/bindings/python/gnucash_core.py b/bindings/python/gnucash_core.py
index 8903f7c555..9336c436ae 100644
--- a/bindings/python/gnucash_core.py
+++ b/bindings/python/gnucash_core.py
@@ -22,6 +22,135 @@
# @author Jeff Green, ParIT Worker Co-operative <jeff at parit.ca>
# The following is for doxygen
+
+## @defgroup python_bindings Python Bindings Module
+# Also have a look at the page @ref python_bindings_page.
+
+## @defgroup python_bindings_examples Python Bindings Examples Module
+# @ingroup python_bindings
+# The python-bindings come with quite a lot of example scripts.
+
+## @page python_bindings_page Python bindings
+# Also have a look at group @ref python_bindings.
+#
+# In the source tree they are located at bindings/python.
+#
+# To enable them in the compilation process you have to add -DWITH_PYTHON=ON
+# to the call of cmake.
+#
+# As a starting point have a look at the \link python_bindings_examples example-scripts\endlink.
+#
+# @section possibilities What can Python Bindings be used for ?
+#
+# The python bindings supply the ability to access a wide range of the core functions of GnuCash. You
+# can read and write Transactions, Commodities, Lots, access the business stuff... You gain the ability
+# to manipulate your financial data with a flexible scripting language.
+#
+# Not everything GnuCash can is possible to access though. The bindings focus on basic accounting functions.
+# Have a look at the examples to get an impression.
+#
+# Some functions are broken because they have not been wrapped properly. They may crash the program or return unaccessible values.
+# Please file a bug report if you find one to help support the development process.
+#
+# @section python_bindings_section Principles
+# The python-bindings are generated using SWIG from parts of the source-files of GnuCash.
+#
+# @note Python-scripts should not be executed while GnuCash runs. GnuCash is designed as
+# a single user application with only one program accessing the data at one time. You can force your
+# access but that may corrupt data. Maybe one day that may change but for the moment there is no active development on that.
+#
+# @subsection swigworks What SWIG does
+#
+# SWIG extracts information from the c-sources and provides access to the structures
+# to python. It's work is controlled by interface files :
+#
+# @li gnucash_core.i
+# @li timespec.i
+# @li glib.i
+# @li @link base-typemaps.i src/base-typemaps.i @endlink This file is shared with Guile.
+#
+# it outputs:
+#
+# @li gnucash_core.c
+# @li gnucash_core_c.py
+#
+# If you have generated your own local doxygen documentation (by "make doc") after having compiled the python-bindings, doxygen
+# will include SWIGs output-files.
+# It's actually quite interesting to have a look at them through doxygen, because they contain all that you can
+# access from python.
+#
+# This c-style-api is the bottom layer. It is a quite raw extract and close to the original source. Some more details are described further down.
+#
+# For some parts there is a second layer of a nice pythonic interface. It is declared
+# in
+# @li gnucash_core.py and
+# @li gnucash_business.py.
+# @li function_class.py contains helper functions for that.
+#
+# @section howto How to use the Python bindings
+# @subsection highlevel High level python wrapper classes
+# If you
+#
+# @code >> import gnucash @endcode
+#
+# You can access the structures of the high level api. For Example you get a Session object by
+#
+# @code >> session=gnucash.Session() @endcode
+#
+# Here you will find easy to use things. But sometimes - and at the current level rather sooner than
+# later - you may be forced to search for solutions at the :
+#
+# @subsection c_style_api C-style-api
+#
+# If you
+#
+# @code >> import gnucash @endcode
+#
+# The c-style-api can be accessed via gnucash.gnucash_core_c. You can have a look at all the possibilities
+# at gnucash_core_c.py.
+#
+# You will find a lot of pointers here which you can just ignore if input and output of the function have the
+# same type.
+#
+# For example you could start a session by gnucash.gnucash_core_c.qof_session_begin(). But if you just try
+#
+# @code session=gnucash.gnucash_core_c.qof_session_begin() @endcode
+#
+# you will get an error message and realize the lack of convenience for you have to add the correct function parameters.
+#
+# Not all of the available structures will work. SWIG just takes everything from the sources that it is fed with and translates it. Not everything
+# is a working translation, because not everything has been worked through. At this point you are getting closer to the developers who you can
+# contact at the mailing-list gnucash-devel at gnucash.org. There may be a workaround. Maybe the problem can only be fixed by changing SWIGs input
+# files to correctly translate the c-source. Feel free to post a question at the developers list. It may awaken the interest of someone who creates
+# some more beautiful python-interfaces.
+#
+# @section Thisorthat When to use which api ?
+#
+# The start would surely be the high-level api for you can be quite sure to have something working and you will maybe find
+# explanations in the example-scripts. If you search for something that is not yet implemented in that way you will have to
+# take your way to the c-style-api.
+#
+# @section pydoc (Further) documentation
+#
+# @li The documentation you just read uses doxygen. It collects documentation in GnuCash's sources. Besides that there is
+# @li the classic python-documentation using help() and docstrings. Have a look at both.
+# @li There is a page in the GnuCash wiki at https://wiki.gnucash.org/wiki/Python
+# @li You may also have a look into the archives of gnucash-devel at gnucash.org.
+# @li On Bugzilla there is also some interesting talk regarding the development process.
+# @li Then you can use the abilities of git to see the history of the code by @code git log @endcode done in the directory of the python-bindings.
+#
+# @section pytodo To-Do
+# @li Work out the relation of scheme/guile and python-bindings
+# @li maybe join python_bindings_page and group
+# @li work on the structure of the documentation to make it more clear
+# @li try to make SWIG include the documentation of the c-source
+# @li make function-links in SWIG-generated files work.
+# @li some words to the tests
+#
+# @author Christoph Holtermann
+# @date December 2010
+
+
## @file
# @brief High level python wrapper classes for the core parts of GnuCash
# @author Mark Jenkins, ParIT Worker Co-operative <mark at parit.ca>
diff --git a/libgnucash/doc/CMakeLists.txt b/libgnucash/doc/CMakeLists.txt
index f02acbcf33..4129533416 100644
--- a/libgnucash/doc/CMakeLists.txt
+++ b/libgnucash/doc/CMakeLists.txt
@@ -4,9 +4,6 @@ set(doc_FILES
doxygen_main_page.c
finderv.html
finutil.html
- loans.txt
- lots.txt
- python-bindings-doxygen.py
README
)
diff --git a/libgnucash/doc/loans.txt b/libgnucash/doc/loans.txt
deleted file mode 100644
index 42a855f1c8..0000000000
--- a/libgnucash/doc/loans.txt
+++ /dev/null
@@ -1,288 +0,0 @@
-/** \page loanhandling Handling loan repayment in GnuCash::Scheduled Transactions
-\sa The original email thread at <https://lists.gnucash.org/pipermail/gnucash-devel/2002-July/006438.html>.
-
-July, 2002 - jsled at asynchronous.org
-
-API: \ref SchedXaction
-
-We define loan repayment values in the following terms:
-
-Identifiers:\n
-P : the original principal. This is the overall principal afforded by the
- loan at the time of it's creation.\n
-P' : The beginning principal. This is the principal at the time of entry
- into GnuCash.\n
-I : The interest rate associated with the loan. Note that this may change
- over time [based on an addition to the Prime rate, for instance], at
- various frequencies [yearly, monthly, quarterly...]. Ideally, we can
- use the FreqSpec mechanism to facilitate the interest rate adjustment.\n
-N : The length of the loan in periods.\n
-m : The minimum periodic payment.\n
-n : The current period of the repayment.
-
-Functions:\n
-PMT : Total equal periodic payment, as per Gnumeric/Excel's definitions
- [see end for more detail].\n
-IPMT : Monthly payment interest portion, ""\n
-PPMT : Monthly payment principal portion, ""
-
-[ NOTE: 'PMT(I,N,P) = IPMT(I, n, N, P) + PPMT(I, n, N, P)' for 0 <= n < N ]
-
-
-The formula entered into the SX template for a loan may then look like:
-
-Example 1:
-\verbatim
-Desc/Memo | Account | Credit | Debit
-----------+-----------------------------+----------------+-------------------
-Repayment | Assets:Bank:Checking | | =PMT(I,n,N,P)
- | | | + fixed_amt
-Interest | Expenses:Loan_Name:Interest | =IPMT(I,n,N,P) |
-PMI | Expenses:Loan_Name:Misc | fixed_amt |
-Principal | Liabilities:Loan_Name | =PPMT(I,n,N,P) |
------------------------------------------------------------------------------
-\endverbatim
-
-Or, in the case where an escrow account is involved [with thanks to warlord
-for the review and fixes]:
-
-Example 2:
-\verbatim
-Desc/Memo | Account | Credit | Debit
----------------+-----------------------------+----------------+--------------
-Repayment | Assets:Bank:Checking | | =PMT(I,n,N,P)
- | | | + escrow_amt
- | | | + fixed_amt
- | | | + pre_payment
-Escrow | Assets:Loan_Escrow_acct | escrow_amt |
-Interest | Expenses:Loan_Name:Interest | =IPMT(I,n,N,P) |
-PMI | Expenses:Loan_Name:Misc | fixed_amt |
-Principal | Liabilities:Loan_Name | =PPMT(I,n,N,P) |
- | | + pre_payment |
-\endverbatim
-
-FreqSpec = 1 month
-\verbatim
------------------------------------------------------------------------------
-
-Desc/Memo | Account | Credit | Debit
----------------+-----------------------------+----------------+--------------
-Insurance | Assets:Loan_Escrow_acct | | insurance_amt
-Insurance | Expenses:Home_Insurance | insurance_amt |
-\endverbatim
-
-FreqSpec = 1 year
-\verbatim
------------------------------------------------------------------------------
-Desc/Memo | Account | Credit | Debit
----------------+-----------------------------+----------------+--------------
-Taxes | Assets:Loan_Escrow_acct | | taxes_amt
-Taxes | Expenses:Property_Taxes | taxes_amt |
-FreqSpec = Quarterly
------------------------------------------------------------------------------
-\endverbatim
-
-
-\section guidpractical Practical questions regarding the implementation of this facility are:
-
-| 1. The transactions as in Example 2 are not going to be scheduled for the\n
-| same day; are their values linked at all / do they need to share the\n
-| same var bindings?
-
-Yes, they would want to be linked. More precisely, the insurance/tax amounts
-are very likely linked to the escrow_amt in Ex.2. Unfortunately, these are
-very likely separate SXes...
-
------
-| 2. How does this effect the SX implementation of variables?
-
-Vastly.
-
-It becomes clear that multiple SXes will be related. While they'll have
-separate FreqSpecs and template transactions, they'll share some state. For
-both visualization [i.e., the SX list] and processing [credit/debit cell
-value computation] we'll want some manner of dealing with this.
-
-It becomes clear as well that the nature of variables and functions needs to
-be more clearly defined with respect to these issues. We probably want to
-institute a clear policy for the scoping of variables. As well, since the
-SXes will have different instantiation dates, we'll need a method and
-implementation for the relation of SXes to each other.
-
-A substantial hurdle is that if a set of SXes are [strongly] related, there
-is no-longer a single instantiation date for a set of related SXes. In fact,
-there may be different frequencies of recurrence.
-
-One option -- on the surface -- to relate them would be to maintain an
-instance variable-binding frame cache, which would store user-entered and
-computed variable bindings. The first instantiated SX of the set would create
-the frame, and the "last" instance would clean it up. First "last" instance
-is defined by the last-occurring SX in a related set, in a given time range.
-
-For example: a loan SX-set is defined by two monthly SXes ["repayment" and
-"insurance"], and a quarterly "tax" SX. The first monthly SX would create a
-frame, which would be passed two the second monthly SX. This would occur for
-the 3 months of interest. The Quarterly SX would get all 3 frames for it's
-creation, and use them in an /appropriate/ [read: to be defined through a lot
-of pain] way. As the time-based dependency relationship between the frames
-plays out, the frame can be removed from the system.
-
-Another option is to toss this idea entirely and instead let the user DTRT
-manually.
-
-A related option is to add the necessary grouping mechanism to the SX
-storage/data structure: immediately allowing visual grouping of related SXes,
-and potentially allowing a storage place for such frame data in the future
-with less file-versioning headache. This is the option that will be pursued.
-
-Another element implicit in the original requirements to support
-loans/repayment calculations is implicit variables. These are symbolic names
-which can be used and are automagically bound to values. The known implicit
-variables to support loan/repayment are:
-
-P [loan principal amount], N [loan repayment periods], I [interest], m
-[minimum payment] and n [current period]. Some of these [P, N, I, m] are
-fixed over many instances; some [n] are rebound specific to the instance.
-See the 'variable-scope-frame' below for a method of handling these
-variables.
-
-And yet-another element implicit in the original requirement is support for
-detecting and computing the result of functions in the template transaction's
-credit/debit cells. Changes to the src/app-utils/gnc-exp-parser.[hc] and
-src/calculation/expression_parser.[ch] to support functions would be
-necessitated. It is conceivable that after parsing, the parsed expression
-could be passed to scheme for evaluation. Hopefully this would make it
-easier to add support for new functions to the SX code via Scheme.
-
-
-| 3. How do we deal with periodic [yearly, semi-yearly] updating of various\n
-| "fixed" variables?
-
-Another change in the way variables are used is that some SXes -- especially
-loan-repayment -- may involve variables which are not tied to the instance of
-the SX, but rather to variables which:
-- are also involved in another SX
-- change with a frequency different than the SX
-- are represented by a relationship to the outside world ["prime + 1.7"]
-
-A partial fix for this problem is to provide multiple levels of scope for
-variable bindings, and expose this to the user by a method of assigning
-[perhaps time-dependent] values to these variables. Variables bound in this
-manner would absolve the user of the need to bind them at SX-creation time.
-
-An added benefit of this would be to allow some users [see Bug#85707] have
-"fixed variable" values for a group of SXes.
-
-In combination with the SX Grouping, this would provide most of a fix for the
-problem described in #2, above. The variable_frame could be used to provide
-the shared-state between related SXes, without imposing quite the same
-burden. This approach is slightly less flexible, but that allows it to be
-implemented more readily, and understood more easily.
-
-A question which comes up when thinking about yearly-changing values such as
-interest rates is if the historical information needs to be versioned. For
-now, we punt on this issue, but hopefully will provide enough of a framework
-for this to be reasonably added in the future.
-
-We define four types of variables supported by this scheme:
-
-implicit : provided only by the system
- e.g.: 'n', the current index of the repayment
-
-transient : have user-defined values, bound at instantiation time.
- e.g.: existing ad-hoc variables in SXes.
-
-static : have a user-defined values, and are not expected to change with
- any measurable frequency. The user may change these at their
- leisure, but no facility to assist or encourage this is
- provided.
- e.g.: paycheck amount, loan principal amount
-
-periodic : have user-defined values which change at specific points in
- time [July 1, yearly]. After the expiration of a variable value,
- it's re-binding will prevent any dependent SXes from being
- created.
- e.g.: loan tax amount, loan interest rate
-
-| 4. From where do we get the dollar amount against which to do the [PI]PMT\n
-| calculation?
-
-The user will specify the parameters of the Loan via some UI... then where
-does the data go?
-
-- KVP data for that account?
-- KVP data for the SX?
-- Do we have a different top-level "Loan" object?
-- Present only in the SX template transactions/variable-frames?
-
-I believe that the only location of the data after Druid creation is in the
-variable-binding frames and the formulae in the template transactions. The
-Druid would thus simply assist the user in creating the following SX-related
-structures:
-
-- SXGroup: Loan Repayment
- - variable_frame
- - P [static]
- - N [static]
- - n [implicit]
- - I [periodic]
- - pmi_amount [periodic]
- - tax_amount [periodic]
- - pre_payment [periodic]
- - insurance_amount [periodic]
-- SX: Payment
- - Bank -> { Escrow,
- Liability:Loan:Principal,
- Expense:Loan:Interest,
- Expense:Loan:Insurance }
-- SX: Tax
- - Escrow -> Expense:Tax
-- SX: Insurance
- - Escrow -> Expense:Insurance
-
-
-\section loansreference Reference
-
-
-\subsection loanssoftware Other software:
-
-Gnumeric supports the following functions WRT payment calculation:
-
-- PMT( rate, nper, pv [, fv, type] )
- PMT returns the amount of payment for a loan based on a constant interest
- rate and constant payments (ea. payment equal).
- @rate : constant interest rate
- @nper : overall number of payments
- @pv : present value
- @fv : future value
- @type : payment type
- - 0 : end of period
- - 1 : beginning of period
-
-- IPMT( rate, per, nper, pv, fv, type )
- IPMT calculates the amount of a payment of an annuity going towards
- interest. Formula for IPMT is:
- IPMT(per) = - principal(per-1) * interest_rate
- where:
- principal(per-1) = amount of the remaining principal from last period.
-
-- ISPMT( rate, per, nper, pv )
- ISPMT returns the interest paid on a given period.
- If @per < 1 or @per > @nper, returns #NUM! err.
-
-- PPMT(rate, per, nper, pv [, fv, type] )
- PPMT calculates the amount of a payment of an annuity going towards
- principal.
- PPMT(per) = PMT - IPMT(per)
- where: PMT is payment
- - IPMT is interest for period per
-
-- PV( rate, nper, pmt [, fv, type] )
- Calculates the present value of an investment
- @rate : periodic interest rate
- @nper : number of compounding periods
- @pmt : payment made each period
- @fv : future value
-
-
-*/
diff --git a/libgnucash/doc/lots.txt b/libgnucash/doc/lots.txt
deleted file mode 100644
index 2fde5ce44c..0000000000
--- a/libgnucash/doc/lots.txt
+++ /dev/null
@@ -1,522 +0,0 @@
-/** \page lotsoverview Lots Architecture & Implementation Overview
-
- Linas Vepstas <linas at linas.org>
- Last Revised May 2004
-
-API \ref Lot
-
-One often needs to know that the item 'bought' in one transaction
-is the same one as the item 'sold' in a different transaction.
-Lots are used to make this association. One Lot holds all of the
-splits that involve the same item. A lot is typically formed when
-the item is bought, and is closed when the item is sold out.
-A lot need not be a single item, it can be a quantity of the same
-thing e.g. 500 gallons of paint (sold off a few gallons at a time).
-Lots are required to correctly implement invoices, inventory,
-depreciation and stock market investment gains.
-
-'Lots' capture a fundamental accounting idea behind AR/AP, billing,
-inventory, capital gains, depreciation and the like. The basic idea
-is that a set of items is tracked together as a 'lot'; the date of
-creation of the lot helps determine when a bill is due, when depreciation
-starts, or the tax rate for capital gains on a stock market investment.
-
-\section lotsdefines Definition
-
-In GnuCash, a 'lot' will consist of a set of splits identified with
-a unique lot number. Any given split can belong to one lot and one
-lot only. All splits in a lot must also belong to the same account.
-Lots have a 'balance': the sum of all the splits in the lot. A lot
-is 'opened' when the first split is assigned to it. The date of that
-split is the 'opening date' of the lot, and its quantity is the
-'opening balance'. A lot is 'closed' when its balance is zero;
-once closed, a lot cannot be re-opened. Open lots are always carried
-forward into the current open book; closed lots are left behind in the
-book in which they were closed.
-
-\section How Lots Are Used
-
-The following sections review how lots are used to implement various
-accounting devices, and some of the related issues.
-
-\subsection Billing
-
-Tracking lots is the 'definition' of A/R and A/P. You want to be able
-to say that this bill is 120 days old, and its balance has been partly
-paid off; and you want to be able to do this whether or not there are
-also other bills, of different ages, to the same company. In GnuCash,
-a 'bill' is tracked as a lot: The 'billing date' is the opening date
-of the lot, and the 'balance due' is the balance of the lot. When the
-bill is 'paid in full', the lot is closed. The average age of
-receivables can be computed by traversing all lots, etc. Additional
-information about bills, such as a due date or payment terms, should
-be stored as kvp values associated with the lot.
-
-\subsection Billing Example
-
-Normally, there is a one-to-one correspondence between bills and
-lots: there is one lot per bill, and one bill per lot. (Note: this
-is not how gnucash invoices are currently implemented; this is a
-proposed implementation.)
-
-For example:
-\verbatim
- invoice #258 customer XXX
- Order placed 20 December 2001
- quant (10) gallons paint $10/each $100
- quant (2) paintbrushes $15/each $30
- sales tax $8.27
- ------------
- Total due $138.27
-
- Payment received 24 january 2002 $50 Balance Due: $88.27
- Payment received 13 february 2002 $60 Balance Due: $28.27
- Payment received 18 march 2002 $28.27 PAID IN FULL
-\endverbatim
-
-In this example, the lot encompasses four transactions, dated
-December, January, February and March. The December transaction
-opens the lot, and gives it a non-zero balance. To be precise,
-the lot actually consists of four splits, belonging to four
-different transactions. All four splits are a part of an imagined
-"Accounts Receivable-Billing" account. The first split is for
-$138.27, the second split is for $50, the third split is for $60,
-and the fourth split is for $28.27. Note that the sales-tax
-split, and th paint/paint-brush splits are *NOT* a part of this
-lot. They are only a part of the transaction that opened this lot.
-
-Note also that this example might also encompass two other lots:
-the transfer of paint may belong to a lot in the "Paint Inventory"
-account, and the split describing the paintbrushes might be a part
-of a lot in the "Paintbrush Inventory" account. These lots should
-not be confused with the invoice lot.
-
-\subsection lotsinventory Inventory
-
-The correct way of handling inventory under GnuCash is to have a
-separate account for each widget type. The account balance represents
-how many widgets there are in the warehouse. Lots offer an additional
-level of detail that can be useful when, for example, the widgets have
-an expiration date (e.g. milk) or vary slightly from batch to batch
-(e.g paint), and creating a new account to track these differences
-would be too heavy-weight.
-
-In order to track widgets as single units (and prohibit fractional
-widgets), set the currency denominator to 1. This will prevent
-fractional widgets from being transferred into/out of an account.
-
-Note that using accounts to track the inventory of a grocery store
-causes an explosion of accounts, and this explosion would overwhelm
-many of the account GUI's in GnuCash. The GUI should probably be
-modified to treat inventory accounts in a special way, e.g. by
-not listing them in account lists, and providing an alternate
-management GUI.
-
-\subsection Capital Gains
-
-In the United States, gains on stock investments are taxed at different
-rates depending on how long they were held before being sold. By using
-lots with an investment account, it becomes easy to track when any given
-share was bought or sold, and thus, the length of time that share was
-held.
-
-Note, however, that using lots might cause some confusion for naive
-users, since some transactions might be split across different lots.
-For example, the user may have conceptually made the following
-transactions:
-
-\verbatim
-> Date Desc Buy Sell Price Value
-> 18/1/01 XCORP 500 $10.00 $5000.00
-> 21/3/01 XCORP 500 $12.00 $6000.00
-> 14/7/02 XCORP 750 $20.00 $15000.00
-\endverbatim
-
-However, the two buy transactions create different lots (because
-you can't add to a stock-investment lot after its been created, because
-the purchases occurred on different dates). Thus, when the shares are
-sold, the sale is split across two lots:
-
-\verbatim
-> Date Desc Lot Buy Sell Price Value
-> 18/1/01 XCORP 187 500 $10.00 $5000.00
-> 21/3/01 XCORP 188 500 $12.00 $6000.00
-> 14/7/02 XCORP 187 500 $20.00 $10000.00
-> 14/7/02 XCORP 188 250 $20.00 $5000.00
-\endverbatim
-
-In the above, lot 187 was closed, and lot 188 has a balance of 250
-shares. Note that we used a FIFO accounting method in this example:
-the oldest shares were sold first.
-
-Note also, that by using lots in this example, we are able to accurately
-compute the gains in this transaction: it is 500*($20-$10) + 250*($20-$12)
-= $5000+$2000 = $7000. If we had used LIFO accounting, and sold the
-youngest shares first, then the profits would have been 500*($20-$12)
-+ 250*($20-$10) = $4000 + 2500 = $6500. Thus, different accounting
-methods do affect income, and thus the tax rate.
-
-Note that the two ledgers, the 'without-lots' and the 'with-lots'
-ledgers look different, even though the conceptual transactions are
-the same. If a naive user was expecting a 'without-lots' ledger,
-and is shown a 'with lots' ledger, they may get confused. I don't
-know of any simple way of dealing with this. In order to have lots
-work (thereby allowing cap gains reports to work correctly), the GnuCash
-engine *must* use the 'with-lots' representation of the data. If the
-GUI wants to hide the fact that there are lots under the covers, it
-must figure out a way of doing this (i.e. re-combining splits) on
-its own.
-
-\section lotsclosing Closing of Books
-
-A few words on lots and the closing of books. Without lots, there
-is really no way of correctly implementing book closing. That is
-because some reports, such as the capital-gains report, need to know
-not only the account balance, but also the purchase dates. Lots
-provide the natural mechanism for storing this information.
-
-When a book is closed, any open lots must be moved into/kept with
-the open book. Since the splits in a lot belong to transactions,
-and transactions are 'atomic', this means that the associated
-transactions must be moved into the open book as well. A lot
-is considered closed when its balance is zero; when a book is closed,
-all of the lots that were closed stay with that book. That is,
-closed lots are not propagated forward into the currently open book.
-
-Actually, its slightly more subtle than that. Not only must open
-lots stay with the open book, but so must all transactions that
-have splits that participate in the open lot, and, by extension,
-all closed lots that participate in these 'open transactions',
-ad infinitum.
-
-\section lotsdouble The "Double Balance" Requirement
-
-The following is a proposal for how to handle both realized
-and unrealized gains/losses by means of "adjusting transactions."
-It works for simple cases, but has issues for more complex cases.
-
-
-Canonical transaction balancing: If all splits in a transaction
-are in the same 'currency' as the transaction currency, then the
-sum of the splits *must* equal zero. This is the old, existing
-double-entry requirement as implemented in Gnucash, and doesn't
-change.
-
-If some splits are in one commodity, and others in another, then
-we can't force a zero balance as above. Instead, we will force
-a different requirement, the 'double-balance' requirement:
-
-- All splits that are *not* in the transaction currency C
- must be made a part of a lot. (Thus, for example,
- the transaction currency C is dollars, whereas the split
- commodity is 'S', shares of RHAT. If a transaction
- has C in dollars, and 'S' in RHAT, then the S split must
- be made a part of a Lot.)
-- The lot will have a designated 'lot currency' L that must
- be the same as the C of every split in the lot. One
- cannot enter a split into the lot if C != L. (That is,
- if I'm working with a Lot of RHAT shares, then *all*
- splits in the lot must belong to dollar-denominated
- transactions.)
-- When a lot is closed, we must have the 'double-balance'
- condition: The sum total of all 'S' is zero, and the
- sum total of all 'C' is zero. Thus, if I buy 100 shares
- of RHAT for $5 and sell 100 shares of RHAT for $10, then
- I *must* also add an 'adjusting transaction' for zero
- shares of RHAT, at $500. If there is no adjusting transaction,
- then the lot cannot be closed. If sum 'S' is zero,
- while sum 'C' is not zero, then the lot is declared to
- be 'out-of-balance', and an 'adjusting transaction' must
- be forced.
-
-It is only by 'closing a lot' that one is able to regain
-'perfect balance' in the books. That is, the 'double-balance'
-requirement is the generalization of the 'double-entry'
-requirement for stock accounts.
-
-Note that because the 'adjusting transaction' has one split
-in dollars, and another split in RHAT shares (albeit for zero
-RHAT shares), it evades the old double-entry requirement,
-and will not be flagged as 'out of balance'. Note also
-that because the 'adjusting transaction' contains a split
-holding S (albeit zero S), it *must* be a part of a Lot.
-
-
-The above seems to work for simple stock-transactions, but
-fails in other more complex cases. Here's an example.
-
-Imagine 'S' is in euros, instead of 'RHAT'. So I sell
-100 dollars, and buy 110 euros. This causes a lot to open
-up for the euros, with the lot currency 'L' in dollars.
-Now I try to transfer the euros to other euro accounts.
-What happens to the lot? Do I have to give up on it?
-How can I save this bad situation?
-
-A similar problem occurs for more complex stock transactions:
-If I buy 100 shares of RHAT with Schwab, and transfer them
-to another account with Etrade, then I have the same lot
-closing problem. There's an even worse scenario, where
-I move to Brazil, and take my RHAT stock (purchased in dollars)
-to my Brazilian broker (who will sell them for cruzeiros).
-
-Is the correct answer to just 'punt' in these cases?
-How is the closing of books to be handled in such a case?
-
-GUI Elements:
-- The user should be able to specify a default 'realized-gain'
- account that is associated with a stock account.
-- The user should be able to specify a default 'unrealized-gain'
- account that is associated with a stock account.
-
-\section lotsfifo FIFO's
-
-What is a FIFO ? A FIFO is a type of accounting policy where
-income from selling inventory is accounted by selling the oldest
-inventory first. Thus, the profit/loss of the sale corresponds
-to the difference in price between when it was bought and sold.
-FIFO's are also used in depreciation schedules, and in other places.
-
-Currently the only policy that is implemented in the cap-gains
-code is the FIFO policy. I believe that it's been abstracted
-properly, so that it should be easy to add other policies,
-e.g. LIFO. See policy.c for what would need to be implemented.
-
-\section lotsimplement Implementation
-
-Every split has a pointer to a lot (which may be null). A lot has a list
-of splits in it (so that the other splits in the lot can be easily found).
-A lot does not need to maintain a balance (this is easy enough to calculate
-on the fly). A lot has a kvp tree (for storage of lot-related date, such
-as due dates for invoices, etc. A lot has a GUID.
-
-From the memory-management and data-base management point of view, lots
-belong to accounts. The GnuCash account structure maintains a list of
-lots so that all lots belonging to an account can be quickly retrieved.
-(In principle, the lots can be found by scanning every split in the
-account, but this is a painful process.)
-
-\section lotscapgains Implementing Cap Gains (Is a Pain in the Neck)
-
-Although Lots provide a good conceptual framework for determining
-gains or losses when a lot is closed, cap-gains on half-open
-lots present additional complexities. Consider the following
-stock purchase and subsequent sale of half the stock:
-
-Account A is a stock account
-
-Account B is a bank account
-
-Account C is an income account
-\verbatim
- Acct A Txn Acct B Acct C
-Date Action Amt Prc Value Amt Amt
-1/1/01 buy 100s $10 $1000 ($1000) -
-2/2/02 sell (50)s $25 $1250 $1250 -
-2/2/02 gain - - $750 $750
-\endverbatim
-
-The gain, shown in the third line, is computed as a straight
-sum of purchase price to sale price.
-
-Should the above be represented as two transactions, or as three?
-One could, in principle, combine the second and third lines into
-one transaction. However, this has some drawbacks: computing
-the overall balance of such a transaction is tricky, because
-it has so many different splits (including, possibly, splits
-for brokerage fees, tax, etc. not shown). The alternative
-is to represent each line as a separate transaction. This has
-other drawbacks: If the date, amount, price or value is adjusted
-for the second transaction, the corresponding values must be
-adjusted for the third, and vice-versa.
-
-Both schemes pose trouble for the register display: we want
-the stock register to show the gain as if it were a part of
-the stock sale; but the third line is a pair of splits, and
-we want to show only one of these two splits. Whichever method
-is chosen, the register has to filter out some of the splits
-that it shows.
-
-The implementation that seems best is to represent the sale
-with two separate transactions: one for the sale itself, and a
-separate one for the gains. This makes computing the balance
-easier, although it makes the logic for setting the date
-more complex. Ughh..
-
-\section loanscapnotes Cap Gains Implementation Notes
-
-Cap Gains will be handled by GnuCash as described above, using
-two distinct transactions. These transactions will be marked up
-using KVP, pointing to each other, so that the one can be found
-from the other. Implementation in src/engine/cap-gains.c
-
-Quick API Overview:
-- xaccSplitGetCapGains(): Returns the capital gains associated with
- a split. Split must have been a sale/purchase in a previously
- opened lot.
-- xaccSplitAssignToLot(): If a split is not already in a lot,
- then it places it into a lot, using a FIFO accounting policy.
-
-\section lotscapimplement Cap Gains Actual Implementation
-
-Cap Gains are noted by creating a separate transaction with two
-splits in it. One of the splits is as described above: zero
-amount, non-zero value. There is a GUI requirement that when
-the looking at a gains transaction, certain things need to be
-kept in sync with the transaction that is the source of the gains.
-In order to accomplish this, the engine uses a set of 'dirty'
-flags, and a pair of pointers between the gains split and the
-source split, so that the one can be quickly found from the other.
-
-Things kept in sync:
-- date posted
-- value
-- void status
-- other things ?
-
-Things not kept in sync:
-- kvp trees
-- description, memo, action.
-
-The posted date is kept in sync using a data-constraint scheme.
-If xaccTransactionSetDatePosted() is called, the date change is
-accepted, and the split is marked date-dirty. When the transaction
-is committed (using xaccTransCommitEdit()), the date-dirty flag
-is evaluated, and, if needed, the date changes are propagated/rolled
-back on the appropriate gains splits. Currently, one can only change
-the date on the gains-source transaction; the date on the
-gains-recording split cannot be changed.
-
-The value recorded by the gains transaction is updated whenever
-the value of the source changes. The actual update is done by
-the xaccSplitComputeCapGains() routine, via xaccScrubLot(), which
-is called at the time of xaccTransCommitEdit(). Note that two
-different things can affect the gains: a change in the value of
-the sale, and a change of the value of the purchase. A set of
-dirty flags are used to track these.
-
-If the amount of a plit changes, then the lot that its in becomes
-potentially unbalanced. This requires the lot membership to be
-recomputed; this in turn may require the split to be split into
-pieces, or to be recombined into one from several pieces.
-
-\section lotstodo TODO
-- need to copy void status when source split date changes.
-- its possible for the the price, as recorded by one split
- to vary wildly from that in another split in the same
- transaction. That's bad, prices should be normalized.
- There's a routine to do this, xaccScrubSubSplitPrice()
- but its not currently used.
-- write automated test cases to handle each situation.
-
-\section lotsconversion Conversion
-
-As Lots are put into production, old GnuCash datasets
-will need to be converted. Conversion will be done by running
-all splits in an account through an accounting policy (currently,
-there is only one policy, a FIFO). The goal of the policy is to
-match up purchases and sales so that these can be assigned to a Lot.
-
-The conversion algorithm will work as follows:
-\verbatim
-for each account {
- loop over splits {
- // perform the 'double-balance' check
- if (split commodity != transaction currency) account needs conversion
- }
- if account needs conversion
- for each split {
- If (split amount > 0) create new lot, put split in lot.
- If (split amount < 0) find oldest lot, put split in that lot
- }
-}
-\endverbatim
-
-See the file Scrub2.h for details of the low-level API, and Scrub3.h
-for the high-level API.
-
-There is a bit of a problem with this conversion procedure: If the
-user had previously recorded cap gains using a 'handmade' version of
-lots, those cap gains will be ignored and will throw off balances.
-User will need to hand-edit to recover.
-
-- TODO: Modify scrub routines to look for splits with zero amount,
- try to assign these to lots as appropriate. ??
-
-\section lotsgui GUI
-
-A GUI for handling Lots is needed: ability to view a lot, and to cut/paste
-or move a split from one lot to another. Need a GUI to create a lot,
-maybe append some notes to it. Need ability to view account in lot-mode.
-
-For automatically managing accounts, need to implement a variety of
-different accounting policies (of which the FIFO policy is currently
-implemented in the 'Scrub' routines).
-
-\subsection lotsbasicgui Basic GUI
- The goal of the basic GUI is to handle most usages of
- most lots in most places. There also need to be special-purpose
- dialogs for specific applications, e.g. stocks, inventory, etc.
-
- Shows three areas:
-- list of lots, one of which can be highlighted.
- Lot names can be edited in-place.
-- contents of a single lot (displayed in a narrow,
- mini-register view, showing only date, memo, quant,
- balance)
-- list of splits not in any lot.
- (not clear if screen real-estate allows side-by-side
- placement, or if this must be above/below. above/below
- would suck)
-
- Shows various buttons:
-- two arrows, which move split into/out of lot.
- This is a traditional way of moving something from one
- list to another, but some UI designers argue against this.
- Is there a better way to move splits into/out-of a lot?
-
-- button, labeled 'close lot', which, when pressed, will
- set lot balance to zero. (by using fifo on the unassigned
- splits, if possible).
-
-- A field showing realized gain/loss on a closed lot, and
- a pull-down allowing the gain/loss to be posted to a
- specific account.
- (The default is stored in kvp:/lots-mgmt/gains-acct/)
-
-- button or menu item, 'add notes to this lot'.
-
-\subsection lotsguitodo todo:
-- change lot viewer to use gnc-query-list
-- after the gnome2 port, add the 'unclaimed splits" window
- to the lot viewer, this will allow it to be a simple lot editor.
-- Add a new policy (or change the existing fifo policy) to only
- open lots with a particular sign for the opening split. This
- way, things like business invoice overpayments are not used
- to start new lots, but are instead applied to new purchases.
-
-\section lotsstatus Status
-
-- Core support for Lots in the engine is complete (April 2002, ships in
- version 1.8.x, used by business backend).
-- See src/engine/gnc-lot.h for the public API.
-- The XML backend support for lot is complete (April 2002, ships in
- version 1.8.x).
-- Scrub routines to automatically take old gnucash datasets and
- transition them to double-balanced lots have been implemented.
- These implement a FIFO accounting policy (April 2003)
-- Closed/Open lots are handled correctly during book closing.
- See src/engine/Period.c (August 2003)
-- Work is finished on the automatic computation & tracking
- of gain/loss transactions. Most of the engine API is in
- src/engine/cap-gains.h although the high-level 'scrub' API
- is in src/engine/Scrub3.h. See src/doc/constraints.txt for
- a 'big picture' view of how its done. (September 2003)
-- A basic lot-viewing GUI is in src/gnome/lot-viewer.c
- This GUI cannot 'edit' lots. (August 2003)
-- Need to write extensive test cases to verify the rather complex
- constraints between the gains and lots and splits.
-- Need to write a cap-gains report!
-
-*/
-
--------------------------- end of file ------------------------------
diff --git a/libgnucash/doc/python-bindings-doxygen.py b/libgnucash/doc/python-bindings-doxygen.py
deleted file mode 100644
index 1f85e6be86..0000000000
--- a/libgnucash/doc/python-bindings-doxygen.py
+++ /dev/null
@@ -1,135 +0,0 @@
-## @file
-# @brief Documentation file for GnuCashs python bindings, input file for doxygen.
-#
-# This file holds the more explanatory parts of the doxygen-source-documentation.
-# You will find the contents at @ref python_bindings_page.
-#
-# @par To-Do:
-# @li Work out the relation of scheme/guile and python-bindings
-# @li maybe join python_bindings_page and group
-# @li work on the structure of the documentation to make it more clear
-# @li try to make SWIG include the documentation of the c-source
-# @li make function-links in SWIG-generated files work.
-# @li some words to the tests
-#
-# @author Christoph Holtermann
-# @date December 2010
-# @ingroup python_bindings
-
-
-## @defgroup python_bindings Python Bindings Module
-# Also have a look at the page @ref python_bindings_page.
-
-## @defgroup python_bindings_examples Python Bindings Examples Module
-# @ingroup python_bindings
-# The python-bindings come with quite a lot of example scripts.
-
-## @page python_bindings_page Python bindings
-# Also have a look at group @ref python_bindings.
-#
-# In the source tree they are located at bindings/python.
-#
-# To enable them in the compilation process you have to add -DWITH_PYTHON=ON
-# to the call of cmake.
-#
-# As a starting point have a look at the \link python_bindings_examples example-scripts\endlink.
-#
-# @section possibilities What can Python Bindings be used for ?
-#
-# The python bindings supply the ability to access a wide range of the core functions of GnuCash. You
-# can read and write Transactions, Commodities, Lots, access the business stuff... You gain the ability
-# to manipulate your financial data with a flexible scripting language.
-#
-# Not everything GnuCash can is possible to access though. The bindings focus on basic accounting functions.
-# Have a look at the examples to get an impression.
-#
-# Some functions are broken because they have not been wrapped properly. They may crash the program or return unaccessible values.
-# Please file a bug report if you find one to help support the development process.
-#
-# @section python_bindings_section Principles
-# The python-bindings are generated using SWIG from parts of the source-files of GnuCash.
-#
-# @note Python-scripts should not be executed while GnuCash runs. GnuCash is designed as
-# a single user application with only one program accessing the data at one time. You can force your
-# access but that may corrupt data. Maybe one day that may change but for the moment there is no active development on that.
-#
-# @subsection swigworks What SWIG does
-#
-# SWIG extracts information from the c-sources and provides access to the structures
-# to python. It's work is controlled by interface files :
-#
-# @li gnucash_core.i
-# @li timespec.i
-# @li glib.i
-# @li @link base-typemaps.i src/base-typemaps.i @endlink This file is shared with Guile.
-#
-# it outputs:
-#
-# @li gnucash_core.c
-# @li gnucash_core_c.py
-#
-# If you have generated your own local doxygen documentation (by "make doc") after having compiled the python-bindings, doxygen
-# will include SWIGs output-files.
-# It's actually quite interesting to have a look at them through doxygen, because they contain all that you can
-# access from python.
-#
-# This c-style-api is the bottom layer. It is a quite raw extract and close to the original source. Some more details are described further down.
-#
-# For some parts there is a second layer of a nice pythonic interface. It is declared
-# in
-# @li gnucash_core.py and
-# @li gnucash_business.py.
-# @li function_class.py contains helper functions for that.
-#
-# @section howto How to use the Python bindings
-# @subsection highlevel High level python wrapper classes
-# If you
-#
-# @code >> import gnucash @endcode
-#
-# You can access the structures of the high level api. For Example you get a Session object by
-#
-# @code >> session=gnucash.Session() @endcode
-#
-# Here you will find easy to use things. But sometimes - and at the current level rather sooner than
-# later - you may be forced to search for solutions at the :
-#
-# @subsection c_style_api C-style-api
-#
-# If you
-#
-# @code >> import gnucash @endcode
-#
-# The c-style-api can be accessed via gnucash.gnucash_core_c. You can have a look at all the possibilities
-# at gnucash_core_c.py.
-#
-# You will find a lot of pointers here which you can just ignore if input and output of the function have the
-# same type.
-#
-# For example you could start a session by gnucash.gnucash_core_c.qof_session_begin(). But if you just try
-#
-# @code session=gnucash.gnucash_core_c.qof_session_begin() @endcode
-#
-# you will get an error message and realize the lack of convenience for you have to add the correct function parameters.
-#
-# Not all of the available structures will work. SWIG just takes everything from the sources that it is fed with and translates it. Not everything
-# is a working translation, because not everything has been worked through. At this point you are getting closer to the developers who you can
-# contact at the mailing-list gnucash-devel at gnucash.org. There may be a workaround. Maybe the problem can only be fixed by changing SWIGs input
-# files to correctly translate the c-source. Feel free to post a question at the developers list. It may awaken the interest of someone who creates
-# some more beautiful python-interfaces.
-#
-# @section Thisorthat When to use which api ?
-#
-# The start would surely be the high-level api for you can be quite sure to have something working and you will maybe find
-# explanations in the example-scripts. If you search for something that is not yet implemented in that way you will have to
-# take your way to the c-style-api.
-#
-# @section pydoc (Further) documentation
-#
-# @li The documentation you just read uses doxygen. It collects documentation in GnuCash's sources. Besides that there is
-# @li the classic python-documentation using help() and docstrings. Have a look at both.
-# @li There is a page in the GnuCash wiki at https://wiki.gnucash.org/wiki/Python
-# @li You may also have a look into the archives of gnucash-devel at gnucash.org.
-# @li On Bugzilla there is also some interesting talk regarding the development process.
-# @li Then you can use the abilities of git to see the history of the code by @code git log @endcode done in the directory of the python-bindings.
-#
diff --git a/libgnucash/engine/CMakeLists.txt b/libgnucash/engine/CMakeLists.txt
index 84b39bb436..07fc821bd0 100644
--- a/libgnucash/engine/CMakeLists.txt
+++ b/libgnucash/engine/CMakeLists.txt
@@ -282,7 +282,6 @@ set(engine_EXTRA_DIST
README
README.query-api
SX-book-p.h
- TaxTableBillTermImmutability.txt
)
if (NOT WIN32)
diff --git a/libgnucash/engine/SchedXaction.h b/libgnucash/engine/SchedXaction.h
index 9e1f65719a..a4bc8d0d8d 100644
--- a/libgnucash/engine/SchedXaction.h
+++ b/libgnucash/engine/SchedXaction.h
@@ -335,3 +335,293 @@ gboolean SXRegister (void);
/** @} */
/** @} */
+
+/** \page loanhandling Handling loan repayment in GnuCash::Scheduled Transactions
+ * \sa The original email thread at <https://lists.gnucash.org/pipermail/gnucash-devel/2002-July/006438.html>.
+ *
+ * July, 2002 - jsled at asynchronous.org
+ *
+ * API: \ref SchedXaction
+ *
+ * We define loan repayment values in the following terms:
+ *
+ * Identifiers:\n
+ * P : the original principal. This is the overall principal afforded by the
+ * loan at the time of it's creation.\n
+ * P' : The beginning principal. This is the principal at the time of entry
+ * into GnuCash.\n
+ * I : The interest rate associated with the loan. Note that this may change
+ * over time [based on an addition to the Prime rate, for instance], at
+ * various frequencies [yearly, monthly, quarterly...]. Ideally, we can
+ * use the FreqSpec mechanism to facilitate the interest rate adjustment.\n
+ * N : The length of the loan in periods.\n
+ * m : The minimum periodic payment.\n
+ * n : The current period of the repayment.
+ *
+ * Functions:\n
+ * PMT : Total equal periodic payment, as per Gnumeric/Excel's definitions
+ * [see end for more detail].\n
+ * IPMT : Monthly payment interest portion, ""\n
+ * PPMT : Monthly payment principal portion, ""
+ *
+ * [ NOTE: 'PMT(I,N,P) = IPMT(I, n, N, P) + PPMT(I, n, N, P)' for 0 <= n < N ]
+ *
+ *
+ * The formula entered into the SX template for a loan may then look like:
+ *
+ * Example 1:
+ * \verbatim
+ * Desc/Memo | Account | Credit | Debit
+ * ----------+-----------------------------+----------------+-------------------
+ * Repayment | Assets:Bank:Checking | | =PMT(I,n,N,P)
+ * | | | + fixed_amt
+ * Interest | Expenses:Loan_Name:Interest | =IPMT(I,n,N,P) |
+ * PMI | Expenses:Loan_Name:Misc | fixed_amt |
+ * Principal | Liabilities:Loan_Name | =PPMT(I,n,N,P) |
+ * -----------------------------------------------------------------------------
+ * \endverbatim
+ *
+ * Or, in the case where an escrow account is involved [with thanks to warlord
+ * for the review and fixes]:
+ *
+ * Example 2:
+ * \verbatim
+ * Desc/Memo | Account | Credit | Debit
+ * ---------------+-----------------------------+----------------+--------------
+ * Repayment | Assets:Bank:Checking | | =PMT(I,n,N,P)
+ * | | | + escrow_amt
+ * | | | + fixed_amt
+ * | | | + pre_payment
+ * Escrow | Assets:Loan_Escrow_acct | escrow_amt |
+ * Interest | Expenses:Loan_Name:Interest | =IPMT(I,n,N,P) |
+ * PMI | Expenses:Loan_Name:Misc | fixed_amt |
+ * Principal | Liabilities:Loan_Name | =PPMT(I,n,N,P) |
+ * | | + pre_payment |
+ * \endverbatim
+ *
+ * FreqSpec = 1 month
+ * \verbatim
+ * -----------------------------------------------------------------------------
+ *
+ * Desc/Memo | Account | Credit | Debit
+ * ---------------+-----------------------------+----------------+--------------
+ * Insurance | Assets:Loan_Escrow_acct | | insurance_amt
+ * Insurance | Expenses:Home_Insurance | insurance_amt |
+ * \endverbatim
+ *
+ * FreqSpec = 1 year
+ * \verbatim
+ * -----------------------------------------------------------------------------
+ * Desc/Memo | Account | Credit | Debit
+ * ---------------+-----------------------------+----------------+--------------
+ * Taxes | Assets:Loan_Escrow_acct | | taxes_amt
+ * Taxes | Expenses:Property_Taxes | taxes_amt |
+ * FreqSpec = Quarterly
+ * -----------------------------------------------------------------------------
+ * \endverbatim
+ *
+ *
+ * \section guidpractical Practical questions regarding the implementation of this facility are:
+ *
+ * | 1. The transactions as in Example 2 are not going to be scheduled for the\n
+ * | same day; are their values linked at all / do they need to share the\n
+ * | same var bindings?
+ *
+ * Yes, they would want to be linked. More precisely, the insurance/tax amounts
+ * are very likely linked to the escrow_amt in Ex.2. Unfortunately, these are
+ * very likely separate SXes...
+ *
+ * -----
+ * | 2. How does this effect the SX implementation of variables?
+ *
+ * Vastly.
+ *
+ * It becomes clear that multiple SXes will be related. While they'll have
+ * separate FreqSpecs and template transactions, they'll share some state. For
+ * both visualization [i.e., the SX list] and processing [credit/debit cell
+ * value computation] we'll want some manner of dealing with this.
+ *
+ * It becomes clear as well that the nature of variables and functions needs to
+ * be more clearly defined with respect to these issues. We probably want to
+ * institute a clear policy for the scoping of variables. As well, since the
+ * SXes will have different instantiation dates, we'll need a method and
+ * implementation for the relation of SXes to each other.
+ *
+ * A substantial hurdle is that if a set of SXes are [strongly] related, there
+ * is no-longer a single instantiation date for a set of related SXes. In fact,
+ * there may be different frequencies of recurrence.
+ *
+ * One option -- on the surface -- to relate them would be to maintain an
+ * instance variable-binding frame cache, which would store user-entered and
+ * computed variable bindings. The first instantiated SX of the set would create
+ * the frame, and the "last" instance would clean it up. First "last" instance
+ * is defined by the last-occurring SX in a related set, in a given time range.
+ *
+ * For example: a loan SX-set is defined by two monthly SXes ["repayment" and
+ * "insurance"], and a quarterly "tax" SX. The first monthly SX would create a
+ * frame, which would be passed two the second monthly SX. This would occur for
+ * the 3 months of interest. The Quarterly SX would get all 3 frames for it's
+ * creation, and use them in an /appropriate/ [read: to be defined through a lot
+ * of pain] way. As the time-based dependency relationship between the frames
+ * plays out, the frame can be removed from the system.
+ *
+ * Another option is to toss this idea entirely and instead let the user DTRT
+ * manually.
+ *
+ * A related option is to add the necessary grouping mechanism to the SX
+ * storage/data structure: immediately allowing visual grouping of related SXes,
+ * and potentially allowing a storage place for such frame data in the future
+ * with less file-versioning headache. This is the option that will be pursued.
+ *
+ * Another element implicit in the original requirements to support
+ * loans/repayment calculations is implicit variables. These are symbolic names
+ * which can be used and are automagically bound to values. The known implicit
+ * variables to support loan/repayment are:
+ *
+ * P [loan principal amount], N [loan repayment periods], I [interest], m
+ * [minimum payment] and n [current period]. Some of these [P, N, I, m] are
+ * fixed over many instances; some [n] are rebound specific to the instance.
+ * See the 'variable-scope-frame' below for a method of handling these
+ * variables.
+ *
+ * And yet-another element implicit in the original requirement is support for
+ * detecting and computing the result of functions in the template transaction's
+ * credit/debit cells. Changes to the src/app-utils/gnc-exp-parser.[hc] and
+ * src/calculation/expression_parser.[ch] to support functions would be
+ * necessitated. It is conceivable that after parsing, the parsed expression
+ * could be passed to scheme for evaluation. Hopefully this would make it
+ * easier to add support for new functions to the SX code via Scheme.
+ *
+ *
+ * | 3. How do we deal with periodic [yearly, semi-yearly] updating of various\n
+ * | "fixed" variables?
+ *
+ * Another change in the way variables are used is that some SXes -- especially
+ * loan-repayment -- may involve variables which are not tied to the instance of
+ * the SX, but rather to variables which:
+ * - are also involved in another SX
+ * - change with a frequency different than the SX
+ * - are represented by a relationship to the outside world ["prime + 1.7"]
+ *
+ * A partial fix for this problem is to provide multiple levels of scope for
+ * variable bindings, and expose this to the user by a method of assigning
+ * [perhaps time-dependent] values to these variables. Variables bound in this
+ * manner would absolve the user of the need to bind them at SX-creation time.
+ *
+ * An added benefit of this would be to allow some users [see Bug#85707] have
+ * "fixed variable" values for a group of SXes.
+ *
+ * In combination with the SX Grouping, this would provide most of a fix for the
+ * problem described in #2, above. The variable_frame could be used to provide
+ * the shared-state between related SXes, without imposing quite the same
+ * burden. This approach is slightly less flexible, but that allows it to be
+ * implemented more readily, and understood more easily.
+ *
+ * A question which comes up when thinking about yearly-changing values such as
+ * interest rates is if the historical information needs to be versioned. For
+ * now, we punt on this issue, but hopefully will provide enough of a framework
+ * for this to be reasonably added in the future.
+ *
+ * We define four types of variables supported by this scheme:
+ *
+ * implicit : provided only by the system
+ * e.g.: 'n', the current index of the repayment
+ *
+ * transient : have user-defined values, bound at instantiation time.
+ * e.g.: existing ad-hoc variables in SXes.
+ *
+ * static : have a user-defined values, and are not expected to change with
+ * any measurable frequency. The user may change these at their
+ * leisure, but no facility to assist or encourage this is
+ * provided.
+ * e.g.: paycheck amount, loan principal amount
+ *
+ * periodic : have user-defined values which change at specific points in
+ * time [July 1, yearly]. After the expiration of a variable value,
+ * it's re-binding will prevent any dependent SXes from being
+ * created.
+ * e.g.: loan tax amount, loan interest rate
+ *
+ * | 4. From where do we get the dollar amount against which to do the [PI]PMT\n
+ * | calculation?
+ *
+ * The user will specify the parameters of the Loan via some UI... then where
+ * does the data go?
+ *
+ * - KVP data for that account?
+ * - KVP data for the SX?
+ * - Do we have a different top-level "Loan" object?
+ * - Present only in the SX template transactions/variable-frames?
+ *
+ * I believe that the only location of the data after Druid creation is in the
+ * variable-binding frames and the formulae in the template transactions. The
+ * Druid would thus simply assist the user in creating the following SX-related
+ * structures:
+ *
+ * - SXGroup: Loan Repayment
+ * - variable_frame
+ * - P [static]
+ * - N [static]
+ * - n [implicit]
+ * - I [periodic]
+ * - pmi_amount [periodic]
+ * - tax_amount [periodic]
+ * - pre_payment [periodic]
+ * - insurance_amount [periodic]
+ * - SX: Payment
+ * - Bank -> { Escrow,
+ * Liability:Loan:Principal,
+ * Expense:Loan:Interest,
+ * Expense:Loan:Insurance }
+ * - SX: Tax
+ * - Escrow -> Expense:Tax
+ * - SX: Insurance
+ * - Escrow -> Expense:Insurance
+ *
+ *
+ * \section loansreference Reference
+ *
+ *
+ * \subsection loanssoftware Other software:
+ *
+ * Gnumeric supports the following functions WRT payment calculation:
+ *
+ * - PMT( rate, nper, pv [, fv, type] )
+ * PMT returns the amount of payment for a loan based on a constant interest
+ * rate and constant payments (ea. payment equal).
+ * @rate : constant interest rate
+ * @nper : overall number of payments
+ * @pv : present value
+ * @fv : future value
+ * @type : payment type
+ * - 0 : end of period
+ * - 1 : beginning of period
+ *
+ * - IPMT( rate, per, nper, pv, fv, type )
+ * IPMT calculates the amount of a payment of an annuity going towards
+ * interest. Formula for IPMT is:
+ * IPMT(per) = - principal(per-1) * interest_rate
+ * where:
+ * principal(per-1) = amount of the remaining principal from last period.
+ *
+ * - ISPMT( rate, per, nper, pv )
+ * ISPMT returns the interest paid on a given period.
+ * If @per < 1 or @per > @nper, returns #NUM! err.
+ *
+ * - PPMT(rate, per, nper, pv [, fv, type] )
+ * PPMT calculates the amount of a payment of an annuity going towards
+ * principal.
+ * PPMT(per) = PMT - IPMT(per)
+ * where: PMT is payment
+ * - IPMT is interest for period per
+ *
+ * - PV( rate, nper, pmt [, fv, type] )
+ * Calculates the present value of an investment
+ * @rate : periodic interest rate
+ * @nper : number of compounding periods
+ * @pmt : payment made each period
+ * @fv : future value
+ *
+ *
+ */
+
diff --git a/libgnucash/engine/TaxTableBillTermImmutability.txt b/libgnucash/engine/TaxTableBillTermImmutability.txt
deleted file mode 100644
index 0f55993028..0000000000
--- a/libgnucash/engine/TaxTableBillTermImmutability.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-/**
- \addtogroup Business
- @{
- \addtogroup ImmutableTaxTableBillTerm TaxTable and BillTerm immutability tracking
-
-Derek Atkins <warlord at mit.edu>
-Version of October 2003
-
-The gncTaxTable and gncBillTerm business objects have parent, child,
-refcount, invisible field in their structures that deserve some
-explanation:
-
-- a child is a 'frozen' instance of a parent. For example, the tax
- percentage in a particular tax table may change over time, but you
- dont want that change to affect already-posted invoices... So you
- make sure there is an immutable 'copy' (read: child) of the tax
- table when you post the invoice and repoint at the child.
-
-- a parent can have many children, but it will only have a 'child'
- pointer if the parent has not been modified. Think of this as a
- copy-on-write mechanism. posted invoices will continue to use the
- _same_ child until the parent is modified, at which point a new
- child will be created.
-
-- invisible means "dont show this in the list". It's so you dont
- get all the children in the tax table list -- you only see parents.
- I suppose this flag could also be called "is-child" as I believe that
- only children can be invisible, and ALL children are invisible.
-
-- refcount is a listing of how many objects are referencing it.
- Basically, it's letting you know how many customer, vendor, entries,
- etc are referencing e.g. a particular tax table object. mostly this
- was done to make sure you cannot delete an in-use taxtable.
-
-- children don't use refcounts, only parents do.
-
-- A child always points to its parent (it can have only 1).
-- A parent has a list of all children.
-- A parent has a pointer to the current 'replica child', if one exists.
-
-*/
diff --git a/libgnucash/engine/gnc-lot.h b/libgnucash/engine/gnc-lot.h
index 3ea131fa81..9bb5d74c54 100644
--- a/libgnucash/engine/gnc-lot.h
+++ b/libgnucash/engine/gnc-lot.h
@@ -194,3 +194,438 @@ GNCLot * gnc_lot_make_default (Account * acc);
#endif /* GNC_LOT_H */
/** @} */
/** @} */
+
+/** \page lotsoverview Lots Architecture & Implementation Overview
+
+ Linas Vepstas <linas at linas.org>
+ Last Revised May 2004
+
+API \ref Lot
+
+One often needs to know that the item 'bought' in one transaction
+is the same one as the item 'sold' in a different transaction.
+Lots are used to make this association. One Lot holds all of the
+splits that involve the same item. A lot is typically formed when
+the item is bought, and is closed when the item is sold out.
+A lot need not be a single item, it can be a quantity of the same
+thing e.g. 500 gallons of paint (sold off a few gallons at a time).
+Lots are required to correctly implement invoices, inventory,
+depreciation and stock market investment gains.
+
+'Lots' capture a fundamental accounting idea behind AR/AP, billing,
+inventory, capital gains, depreciation and the like. The basic idea
+is that a set of items is tracked together as a 'lot'; the date of
+creation of the lot helps determine when a bill is due, when depreciation
+starts, or the tax rate for capital gains on a stock market investment.
+
+\section lotsdefines Definition
+
+In GnuCash, a 'lot' will consist of a set of splits identified with
+a unique lot number. Any given split can belong to one lot and one
+lot only. All splits in a lot must also belong to the same account.
+Lots have a 'balance': the sum of all the splits in the lot. A lot
+is 'opened' when the first split is assigned to it. The date of that
+split is the 'opening date' of the lot, and its quantity is the
+'opening balance'. A lot is 'closed' when its balance is zero;
+once closed, a lot cannot be re-opened. Open lots are always carried
+forward into the current open book; closed lots are left behind in the
+book in which they were closed.
+
+\section How Lots Are Used
+
+The following sections review how lots are used to implement various
+accounting devices, and some of the related issues.
+
+\subsection Billing
+
+Tracking lots is the 'definition' of A/R and A/P. You want to be able
+to say that this bill is 120 days old, and its balance has been partly
+paid off; and you want to be able to do this whether or not there are
+also other bills, of different ages, to the same company. In GnuCash,
+a 'bill' is tracked as a lot: The 'billing date' is the opening date
+of the lot, and the 'balance due' is the balance of the lot. When the
+bill is 'paid in full', the lot is closed. The average age of
+receivables can be computed by traversing all lots, etc. Additional
+information about bills, such as a due date or payment terms, should
+be stored as kvp values associated with the lot.
+
+\subsection Billing Example
+
+Normally, there is a one-to-one correspondence between bills and
+lots: there is one lot per bill, and one bill per lot. (Note: this
+is not how gnucash invoices are currently implemented; this is a
+proposed implementation.)
+
+For example:
+\verbatim
+ invoice #258 customer XXX
+ Order placed 20 December 2001
+ quant (10) gallons paint $10/each $100
+ quant (2) paintbrushes $15/each $30
+ sales tax $8.27
+ ------------
+ Total due $138.27
+
+ Payment received 24 january 2002 $50 Balance Due: $88.27
+ Payment received 13 february 2002 $60 Balance Due: $28.27
+ Payment received 18 march 2002 $28.27 PAID IN FULL
+\endverbatim
+
+In this example, the lot encompasses four transactions, dated
+December, January, February and March. The December transaction
+opens the lot, and gives it a non-zero balance. To be precise,
+the lot actually consists of four splits, belonging to four
+different transactions. All four splits are a part of an imagined
+"Accounts Receivable-Billing" account. The first split is for
+$138.27, the second split is for $50, the third split is for $60,
+and the fourth split is for $28.27. Note that the sales-tax
+split, and th paint/paint-brush splits are *NOT* a part of this
+lot. They are only a part of the transaction that opened this lot.
+
+Note also that this example might also encompass two other lots:
+the transfer of paint may belong to a lot in the "Paint Inventory"
+account, and the split describing the paintbrushes might be a part
+of a lot in the "Paintbrush Inventory" account. These lots should
+not be confused with the invoice lot.
+
+\subsection lotsinventory Inventory
+
+The correct way of handling inventory under GnuCash is to have a
+separate account for each widget type. The account balance represents
+how many widgets there are in the warehouse. Lots offer an additional
+level of detail that can be useful when, for example, the widgets have
+an expiration date (e.g. milk) or vary slightly from batch to batch
+(e.g paint), and creating a new account to track these differences
+would be too heavy-weight.
+
+In order to track widgets as single units (and prohibit fractional
+widgets), set the currency denominator to 1. This will prevent
+fractional widgets from being transferred into/out of an account.
+
+Note that using accounts to track the inventory of a grocery store
+causes an explosion of accounts, and this explosion would overwhelm
+many of the account GUI's in GnuCash. The GUI should probably be
+modified to treat inventory accounts in a special way, e.g. by
+not listing them in account lists, and providing an alternate
+management GUI.
+
+\subsection Capital Gains
+
+In the United States, gains on stock investments are taxed at different
+rates depending on how long they were held before being sold. By using
+lots with an investment account, it becomes easy to track when any given
+share was bought or sold, and thus, the length of time that share was
+held.
+
+Note, however, that using lots might cause some confusion for naive
+users, since some transactions might be split across different lots.
+For example, the user may have conceptually made the following
+transactions:
+
+\verbatim
+> Date Desc Buy Sell Price Value
+> 18/1/01 XCORP 500 $10.00 $5000.00
+> 21/3/01 XCORP 500 $12.00 $6000.00
+> 14/7/02 XCORP 750 $20.00 $15000.00
+\endverbatim
+
+However, the two buy transactions create different lots (because
+you can't add to a stock-investment lot after its been created, because
+the purchases occurred on different dates). Thus, when the shares are
+sold, the sale is split across two lots:
+
+\verbatim
+> Date Desc Lot Buy Sell Price Value
+> 18/1/01 XCORP 187 500 $10.00 $5000.00
+> 21/3/01 XCORP 188 500 $12.00 $6000.00
+> 14/7/02 XCORP 187 500 $20.00 $10000.00
+> 14/7/02 XCORP 188 250 $20.00 $5000.00
+\endverbatim
+
+In the above, lot 187 was closed, and lot 188 has a balance of 250
+shares. Note that we used a FIFO accounting method in this example:
+the oldest shares were sold first.
+
+Note also, that by using lots in this example, we are able to accurately
+compute the gains in this transaction: it is 500*($20-$10) + 250*($20-$12)
+= $5000+$2000 = $7000. If we had used LIFO accounting, and sold the
+youngest shares first, then the profits would have been 500*($20-$12)
++ 250*($20-$10) = $4000 + 2500 = $6500. Thus, different accounting
+methods do affect income, and thus the tax rate.
+
+Note that the two ledgers, the 'without-lots' and the 'with-lots'
+ledgers look different, even though the conceptual transactions are
+the same. If a naive user was expecting a 'without-lots' ledger,
+and is shown a 'with lots' ledger, they may get confused. I don't
+know of any simple way of dealing with this. In order to have lots
+work (thereby allowing cap gains reports to work correctly), the GnuCash
+engine *must* use the 'with-lots' representation of the data. If the
+GUI wants to hide the fact that there are lots under the covers, it
+must figure out a way of doing this (i.e. re-combining splits) on
+its own.
+
+\section lotsclosing Closing of Books
+
+A few words on lots and the closing of books. Without lots, there
+is really no way of correctly implementing book closing. That is
+because some reports, such as the capital-gains report, need to know
+not only the account balance, but also the purchase dates. Lots
+provide the natural mechanism for storing this information.
+
+When a book is closed, any open lots must be moved into/kept with
+the open book. Since the splits in a lot belong to transactions,
+and transactions are 'atomic', this means that the associated
+transactions must be moved into the open book as well. A lot
+is considered closed when its balance is zero; when a book is closed,
+all of the lots that were closed stay with that book. That is,
+closed lots are not propagated forward into the currently open book.
+
+Actually, its slightly more subtle than that. Not only must open
+lots stay with the open book, but so must all transactions that
+have splits that participate in the open lot, and, by extension,
+all closed lots that participate in these 'open transactions',
+ad infinitum.
+
+\section lotsdouble The "Double Balance" Requirement
+
+The following is a proposal for how to handle both realized
+and unrealized gains/losses by means of "adjusting transactions."
+It works for simple cases, but has issues for more complex cases.
+
+
+Canonical transaction balancing: If all splits in a transaction
+are in the same 'currency' as the transaction currency, then the
+sum of the splits *must* equal zero. This is the old, existing
+double-entry requirement as implemented in Gnucash, and doesn't
+change.
+
+If some splits are in one commodity, and others in another, then
+we can't force a zero balance as above. Instead, we will force
+a different requirement, the 'double-balance' requirement:
+
+- All splits that are *not* in the transaction currency C
+ must be made a part of a lot. (Thus, for example,
+ the transaction currency C is dollars, whereas the split
+ commodity is 'S', shares of RHAT. If a transaction
+ has C in dollars, and 'S' in RHAT, then the S split must
+ be made a part of a Lot.)
+- The lot will have a designated 'lot currency' L that must
+ be the same as the C of every split in the lot. One
+ cannot enter a split into the lot if C != L. (That is,
+ if I'm working with a Lot of RHAT shares, then *all*
+ splits in the lot must belong to dollar-denominated
+ transactions.)
+- When a lot is closed, we must have the 'double-balance'
+ condition: The sum total of all 'S' is zero, and the
+ sum total of all 'C' is zero. Thus, if I buy 100 shares
+ of RHAT for $5 and sell 100 shares of RHAT for $10, then
+ I *must* also add an 'adjusting transaction' for zero
+ shares of RHAT, at $500. If there is no adjusting transaction,
+ then the lot cannot be closed. If sum 'S' is zero,
+ while sum 'C' is not zero, then the lot is declared to
+ be 'out-of-balance', and an 'adjusting transaction' must
+ be forced.
+
+It is only by 'closing a lot' that one is able to regain
+'perfect balance' in the books. That is, the 'double-balance'
+requirement is the generalization of the 'double-entry'
+requirement for stock accounts.
+
+Note that because the 'adjusting transaction' has one split
+in dollars, and another split in RHAT shares (albeit for zero
+RHAT shares), it evades the old double-entry requirement,
+and will not be flagged as 'out of balance'. Note also
+that because the 'adjusting transaction' contains a split
+holding S (albeit zero S), it *must* be a part of a Lot.
+
+
+The above seems to work for simple stock-transactions, but
+fails in other more complex cases. Here's an example.
+
+Imagine 'S' is in euros, instead of 'RHAT'. So I sell
+100 dollars, and buy 110 euros. This causes a lot to open
+up for the euros, with the lot currency 'L' in dollars.
+Now I try to transfer the euros to other euro accounts.
+What happens to the lot? Do I have to give up on it?
+How can I save this bad situation?
+
+A similar problem occurs for more complex stock transactions:
+If I buy 100 shares of RHAT with Schwab, and transfer them
+to another account with Etrade, then I have the same lot
+closing problem. There's an even worse scenario, where
+I move to Brazil, and take my RHAT stock (purchased in dollars)
+to my Brazilian broker (who will sell them for cruzeiros).
+
+Is the correct answer to just 'punt' in these cases?
+How is the closing of books to be handled in such a case?
+
+GUI Elements:
+- The user should be able to specify a default 'realized-gain'
+ account that is associated with a stock account.
+- The user should be able to specify a default 'unrealized-gain'
+ account that is associated with a stock account.
+
+\section lotsfifo FIFO's
+
+What is a FIFO ? A FIFO is a type of accounting policy where
+income from selling inventory is accounted by selling the oldest
+inventory first. Thus, the profit/loss of the sale corresponds
+to the difference in price between when it was bought and sold.
+FIFO's are also used in depreciation schedules, and in other places.
+
+Currently the only policy that is implemented in the cap-gains
+code is the FIFO policy. I believe that it's been abstracted
+properly, so that it should be easy to add other policies,
+e.g. LIFO. See policy.c for what would need to be implemented.
+
+\section lotsimplement Implementation
+
+Every split has a pointer to a lot (which may be null). A lot has a list
+of splits in it (so that the other splits in the lot can be easily found).
+A lot does not need to maintain a balance (this is easy enough to calculate
+on the fly). A lot has a kvp tree (for storage of lot-related date, such
+as due dates for invoices, etc. A lot has a GUID.
+
+From the memory-management and data-base management point of view, lots
+belong to accounts. The GnuCash account structure maintains a list of
+lots so that all lots belonging to an account can be quickly retrieved.
+(In principle, the lots can be found by scanning every split in the
+account, but this is a painful process.)
+
+\section lotscapgains Implementing Cap Gains (Is a Pain in the Neck)
+
+Although Lots provide a good conceptual framework for determining
+gains or losses when a lot is closed, cap-gains on half-open
+lots present additional complexities. Consider the following
+stock purchase and subsequent sale of half the stock:
+
+Account A is a stock account
+
+Account B is a bank account
+
+Account C is an income account
+\verbatim
+ Acct A Txn Acct B Acct C
+Date Action Amt Prc Value Amt Amt
+1/1/01 buy 100s $10 $1000 ($1000) -
+2/2/02 sell (50)s $25 $1250 $1250 -
+2/2/02 gain - - $750 $750
+\endverbatim
+
+The gain, shown in the third line, is computed as a straight
+sum of purchase price to sale price.
+
+Should the above be represented as two transactions, or as three?
+One could, in principle, combine the second and third lines into
+one transaction. However, this has some drawbacks: computing
+the overall balance of such a transaction is tricky, because
+it has so many different splits (including, possibly, splits
+for brokerage fees, tax, etc. not shown). The alternative
+is to represent each line as a separate transaction. This has
+other drawbacks: If the date, amount, price or value is adjusted
+for the second transaction, the corresponding values must be
+adjusted for the third, and vice-versa.
+
+Both schemes pose trouble for the register display: we want
+the stock register to show the gain as if it were a part of
+the stock sale; but the third line is a pair of splits, and
+we want to show only one of these two splits. Whichever method
+is chosen, the register has to filter out some of the splits
+that it shows.
+
+The implementation that seems best is to represent the sale
+with two separate transactions: one for the sale itself, and a
+separate one for the gains. This makes computing the balance
+easier, although it makes the logic for setting the date
+more complex. Ughh..
+
+\section loanscapnotes Cap Gains Implementation Notes
+
+Cap Gains will be handled by GnuCash as described above, using
+two distinct transactions. These transactions will be marked up
+using KVP, pointing to each other, so that the one can be found
+from the other. Implementation in src/engine/cap-gains.c
+
+Quick API Overview:
+- xaccSplitGetCapGains(): Returns the capital gains associated with
+ a split. Split must have been a sale/purchase in a previously
+ opened lot.
+- xaccSplitAssignToLot(): If a split is not already in a lot,
+ then it places it into a lot, using a FIFO accounting policy.
+
+\section lotscapimplement Cap Gains Actual Implementation
+
+Cap Gains are noted by creating a separate transaction with two
+splits in it. One of the splits is as described above: zero
+amount, non-zero value. There is a GUI requirement that when
+the looking at a gains transaction, certain things need to be
+kept in sync with the transaction that is the source of the gains.
+In order to accomplish this, the engine uses a set of 'dirty'
+flags, and a pair of pointers between the gains split and the
+source split, so that the one can be quickly found from the other.
+
+Things kept in sync:
+- date posted
+- value
+- void status
+- other things ?
+
+Things not kept in sync:
+- kvp trees
+- description, memo, action.
+
+The posted date is kept in sync using a data-constraint scheme.
+If xaccTransactionSetDatePosted() is called, the date change is
+accepted, and the split is marked date-dirty. When the transaction
+is committed (using xaccTransCommitEdit()), the date-dirty flag
+is evaluated, and, if needed, the date changes are propagated/rolled
+back on the appropriate gains splits. Currently, one can only change
+the date on the gains-source transaction; the date on the
+gains-recording split cannot be changed.
+
+The value recorded by the gains transaction is updated whenever
+the value of the source changes. The actual update is done by
+the xaccSplitComputeCapGains() routine, via xaccScrubLot(), which
+is called at the time of xaccTransCommitEdit(). Note that two
+different things can affect the gains: a change in the value of
+the sale, and a change of the value of the purchase. A set of
+dirty flags are used to track these.
+
+If the amount of a split changes, then the lot that its in becomes
+potentially unbalanced. This requires the lot membership to be
+recomputed; this in turn may require the split to be split into
+pieces, or to be recombined into one from several pieces.
+
+\section lotsconversion Conversion
+
+As Lots are put into production, old GnuCash datasets
+will need to be converted. Conversion will be done by running
+all splits in an account through an accounting policy (currently,
+there is only one policy, a FIFO). The goal of the policy is to
+match up purchases and sales so that these can be assigned to a Lot.
+
+The conversion algorithm will work as follows:
+\verbatim
+for each account {
+ loop over splits {
+ // perform the 'double-balance' check
+ if (split commodity != transaction currency) account needs conversion
+ }
+ if account needs conversion
+ for each split {
+ If (split amount > 0) create new lot, put split in lot.
+ If (split amount < 0) find oldest lot, put split in that lot
+ }
+}
+\endverbatim
+
+See the file Scrub2.h for details of the low-level API, and Scrub3.h
+for the high-level API.
+
+There is a bit of a problem with this conversion procedure: If the
+user had previously recorded cap gains using a 'handmade' version of
+lots, those cap gains will be ignored and will throw off balances.
+User will need to hand-edit to recover.
+
+
+*/
diff --git a/libgnucash/engine/gncBusiness.h b/libgnucash/engine/gncBusiness.h
index aef11b0b33..0b5bdb86aa 100644
--- a/libgnucash/engine/gncBusiness.h
+++ b/libgnucash/engine/gncBusiness.h
@@ -27,9 +27,47 @@
* @author Copyright (C) 2002 Derek Atkins
* @author Derek Atkins <warlord at MIT.EDU>
*/
+/**
+ @page ImmutableTaxTableBillTerm Some notes on tracking fields in gncBillTerm and gncTaxTable objects
+
+ The gncTaxTable and gncBillTerm business objects have parent, child,
+ refcount, invisible field in their structures that deserve some
+ explanation:
+
+ - a child is a 'frozen' instance of a parent. For example, the tax
+ percentage in a particular tax table may change over time, but you
+ dont want that change to affect already-posted invoices... So you
+ make sure there is an immutable 'copy' (read: child) of the tax
+ table when you post the invoice and repoint at the child.
+
+ - a parent can have many children, but it will only have a 'child'
+ pointer if the parent has not been modified. Think of this as a
+ copy-on-write mechanism. posted invoices will continue to use the
+ _same_ child until the parent is modified, at which point a new
+ child will be created.
+
+ - invisible means "dont show this in the list". It's so you dont
+ get all the children in the tax table list -- you only see parents.
+ I suppose this flag could also be called "is-child" as I believe that
+ only children can be invisible, and ALL children are invisible.
+
+ - refcount is a listing of how many objects are referencing it.
+ Basically, it's letting you know how many customer, vendor, entries,
+ etc are referencing e.g. a particular tax table object. mostly this
+ was done to make sure you cannot delete an in-use taxtable.
+
+ - children don't use refcounts, only parents do.
+
+ - A child always points to its parent (it can have only 1).
+ - A parent has a list of all children.
+ - A parent has a pointer to the current 'replica child', if one exists.
+
+ */
/** @} */
/** @} */
+
+
#ifndef GNC_BUSINESS_H_
#define GNC_BUSINESS_H_
diff --git a/libgnucash/engine/gncTaxTable.h b/libgnucash/engine/gncTaxTable.h
index 4b0fe0affb..8756bf9c7d 100644
--- a/libgnucash/engine/gncTaxTable.h
+++ b/libgnucash/engine/gncTaxTable.h
@@ -22,6 +22,13 @@
/** @addtogroup Business
@{ */
/** @addtogroup TaxTable
+ Define an object to track tax properties for invoices.
+
+ @note A tax table added to an invoice is immutable, that is it
+ can't change any more. To achieve that a tax table is copied when
+ added to an invoice. This uses some internal fields to track this which
+ are explained in @ref ImmutableTaxTableBillTerm.
+
@{ */
/** @file gncTaxTable.h
@brief Tax Table programming interface
commit 6cd8e4e4584cc2a3423a64dd8d5d62c32a8c5b89
Author: Geert Janssens <geert at kobaltwit.be>
Date: Wed May 22 17:59:52 2024 +0200
Doxygen - drop obvious cases of deprecated code
diff --git a/gnucash/gnome/window-autoclear.c b/gnucash/gnome/window-autoclear.c
index 7f9cc18cf1..c9039f5aa3 100644
--- a/gnucash/gnome/window-autoclear.c
+++ b/gnucash/gnome/window-autoclear.c
@@ -105,7 +105,7 @@ show_cleared_splits (GList *splits)
for (GList *iter = splits; iter; iter = iter->next)
{
- GncGUID guid = xaccSplitReturnGUID (iter->data);
+ GncGUID guid = iter->data ? *xaccSplitGetGUID (iter->data) : *guid_null() ;
xaccQueryAddGUIDMatch (guid_query, &guid, GNC_ID_SPLIT, QOF_QUERY_OR);
}
book_query = qof_query_merge (book_query, guid_query, QOF_QUERY_AND);
diff --git a/libgnucash/engine/Split.h b/libgnucash/engine/Split.h
index 0877edcb00..e3889c832f 100644
--- a/libgnucash/engine/Split.h
+++ b/libgnucash/engine/Split.h
@@ -555,8 +555,6 @@ gnc_numeric xaccSplitVoidFormerValue(const Split *split);
/** \deprecated */
#define xaccSplitGetGUID(X) qof_entity_get_guid(QOF_INSTANCE(X))
-/** \deprecated */
-#define xaccSplitReturnGUID(X) (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null()))
#ifdef __cplusplus
} /* extern "C" */
diff --git a/libgnucash/engine/Transaction.h b/libgnucash/engine/Transaction.h
index 04b7f3cebd..b58310ddf9 100644
--- a/libgnucash/engine/Transaction.h
+++ b/libgnucash/engine/Transaction.h
@@ -802,8 +802,6 @@ void xaccTransRecordPrice (Transaction *trans, PriceSource source);
#define xaccTransGetBook(X) qof_instance_get_book (QOF_INSTANCE(X))
/** \deprecated */
#define xaccTransGetGUID(X) qof_entity_get_guid(QOF_INSTANCE(X))
-/** \deprecated */
-#define xaccTransReturnGUID(X) (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null()))
#ifdef __cplusplus
} /* extern "C" */
diff --git a/libgnucash/engine/gnc-date.h b/libgnucash/engine/gnc-date.h
index 2193d0de10..2b0c251862 100644
--- a/libgnucash/engine/gnc-date.h
+++ b/libgnucash/engine/gnc-date.h
@@ -141,10 +141,6 @@ typedef enum
QOF_DATE_COMPLETION_SLIDING, /**< use sliding 12-month window */
} QofDateCompletion;
-/** \deprecated qof_date_format_get_format has been replaced
-by qof_date_text_format_get_string */
-#define qof_date_format_get_format qof_date_text_format_get_string
-
/**
* This is how to format the month, as a number, an abbreviated string,
* or the full name.
diff --git a/libgnucash/engine/gnc-uri-utils.c b/libgnucash/engine/gnc-uri-utils.c
index 599c1ef920..fd962dc2bb 100755
--- a/libgnucash/engine/gnc-uri-utils.c
+++ b/libgnucash/engine/gnc-uri-utils.c
@@ -427,25 +427,3 @@ gchar *gnc_uri_add_extension ( const gchar *uri, const gchar *extension )
/* Ok, all tests passed, let's add the extension */
return g_strconcat( uri, extension, NULL );
}
-
-
-/* Deprecated functions
- * ********************/
-
-/* replaced with gnc_uri_get_scheme */
-gchar *gnc_uri_get_protocol (const gchar *uri)
-{
- return gnc_uri_get_scheme (uri);
-}
-
-/* replaced with gnc_uri_is_known_scheme */
-gboolean gnc_uri_is_known_protocol (const gchar *protocol)
-{
- return gnc_uri_is_known_scheme(protocol);
-}
-
-/* replaced with gnc_uri_is_file_scheme */
-gboolean gnc_uri_is_file_protocol (const gchar *protocol)
-{
- return gnc_uri_is_file_scheme (protocol);
-}
diff --git a/libgnucash/engine/gnc-uri-utils.h b/libgnucash/engine/gnc-uri-utils.h
index 492c048dde..68e4aca2b7 100644
--- a/libgnucash/engine/gnc-uri-utils.h
+++ b/libgnucash/engine/gnc-uri-utils.h
@@ -266,54 +266,6 @@ gboolean gnc_uri_targets_local_fs (const gchar *uri);
*/
gchar *gnc_uri_add_extension ( const gchar *uri, const gchar *extension );
-
-/** @name Deprecated functions
- * @{
- */
-
-/** Extracts the protocol from a uri
- *
- * @deprecated This function has been deprecated in gnucash 3.4. Please use gnc_uri_get_scheme instead.
- *
- * The function allocates memory for the protocol. The calling function should
- * free this memory with g_free if it no longer needs the string.
- *
- * @param uri The uri to extract the protocol from
- *
- * @return The protocol for this uri. If the uri didn't have an
- * explicit protocol, NULL will be returned.
- */
-
-gchar *gnc_uri_get_protocol (const gchar *uri)
- GNC_DEPRECATED("Please use gnc_uri_get_scheme instead (since 3.4)");
-
-/** Checks if there is a backend that explicitly stated to handle the given protocol.
- *
- * @deprecated This function has been deprecated in gnucash 3.4. Please use gnc_uri_is_known_scheme instead.
- *
- * @param protocol The protocol to check
- *
- * @return TRUE if at least one backend explicitly handles this protocol, otherwise FALSE
- */
-gboolean gnc_uri_is_known_protocol (const gchar *protocol)
- GNC_DEPRECATED("Please use gnc_uri_known_scheme instead (since 3.4)");
-
-
-/** Checks if the given protocol is used to refer to a file
- * (as opposed to a network service like a database or web url)
- *
- * @deprecated This function has been deprecated in gnucash 3.4. Please use gnc_uri_is_file_scheme instead.
- *
- * @param protocol The protocol to check
- *
- * @return TRUE if the protocol is used with files, FALSE of the protocol
- * is normally used with network services (database, web url,...)
- */
-gboolean gnc_uri_is_file_protocol (const gchar *protocol)
- GNC_DEPRECATED("Please use gnc_uri_is_file_scheme instead (since 3.4)");
-
-/** @} */
-
#ifdef __cplusplus
}
#endif
diff --git a/libgnucash/engine/qofbook-p.h b/libgnucash/engine/qofbook-p.h
index adbf4369b4..80a79f7bea 100644
--- a/libgnucash/engine/qofbook-p.h
+++ b/libgnucash/engine/qofbook-p.h
@@ -59,11 +59,6 @@ void qof_book_set_backend (QofBook *book, QofBackend *be);
/* Register books with the engine */
gboolean qof_book_register (void);
-/** @deprecated use qof_instance_set_guid instead but only in
-backends (when reading the GncGUID from the data source). */
-#define qof_book_set_guid(book,guid) \
- qof_instance_set_guid(QOF_INSTANCE(book), guid)
-
/** Validate a counter format string with a given format specifier.
* If valid, returns a normalized format string,
* that is whatever long int specifier was used will be replaced with the value of
diff --git a/libgnucash/engine/qofquery.cpp b/libgnucash/engine/qofquery.cpp
index 354724fe7b..b36a0ba3b1 100644
--- a/libgnucash/engine/qofquery.cpp
+++ b/libgnucash/engine/qofquery.cpp
@@ -110,6 +110,25 @@ typedef struct _QofQueryCB
gint count;
} QofQueryCB;
+/* Query Print functions for use with qof_log_set_level, static prototypes */
+static GList *qof_query_printSearchFor (QofQuery * query, GList * output);
+static GList *qof_query_printTerms (QofQuery * query, GList * output);
+static GList *qof_query_printSorts (QofQuerySort *s[], const gint numSorts,
+ GList * output);
+static GList *qof_query_printAndTerms (GList * terms, GList * output);
+static const char *qof_query_printStringForHow (QofQueryCompare how);
+static const char *qof_query_printStringMatch (QofStringMatch s);
+static const char *qof_query_printDateMatch (QofDateMatch d);
+static const char *qof_query_printNumericMatch (QofNumericMatch n);
+static const char *qof_query_printGuidMatch (QofGuidMatch g);
+static const char *qof_query_printCharMatch (QofCharMatch c);
+static GList *qof_query_printPredData (QofQueryPredData *pd, GList *lst);
+static GString *qof_query_printParamPath (QofQueryParamList * parmList);
+static void qof_query_printValueForParam (QofQueryPredData *pd, GString * gs);
+static void qof_query_printOutput (GList * output);
+static void qof_query_print (QofQuery * query);
+
+
/* initial_term will be owned by the new Query */
static void query_init (QofQuery *q, QofQueryTerm *initial_term)
{
@@ -1493,30 +1512,6 @@ gboolean qof_query_equal (const QofQuery *q1, const QofQuery *q2)
/* Query Print functions for use with qof_log_set_level.
*/
-/* Static prototypes */
-static GList *qof_query_printSearchFor (QofQuery * query, GList * output);
-static GList *qof_query_printTerms (QofQuery * query, GList * output);
-static GList *qof_query_printSorts (QofQuerySort *s[], const gint numSorts,
- GList * output);
-static GList *qof_query_printAndTerms (GList * terms, GList * output);
-static const char *qof_query_printStringForHow (QofQueryCompare how);
-static const char *qof_query_printStringMatch (QofStringMatch s);
-static const char *qof_query_printDateMatch (QofDateMatch d);
-static const char *qof_query_printNumericMatch (QofNumericMatch n);
-static const char *qof_query_printGuidMatch (QofGuidMatch g);
-static const char *qof_query_printCharMatch (QofCharMatch c);
-static GList *qof_query_printPredData (QofQueryPredData *pd, GList *lst);
-static GString *qof_query_printParamPath (QofQueryParamList * parmList);
-static void qof_query_printValueForParam (QofQueryPredData *pd, GString * gs);
-static void qof_query_printOutput (GList * output);
-
-/** \deprecated access via qof_log instead.
- The query will be logged automatically if
- qof_log_set_level(QOF_MOD_QUERY, ...) is set to QOF_LOG_DEBUG.
-
- This function cycles through a QofQuery object, and
- prints out the values of the various members of the query
-*/
void
qof_query_print (QofQuery * query)
{
diff --git a/libgnucash/engine/qofquery.h b/libgnucash/engine/qofquery.h
index 1bfc70cb03..791315c6ce 100644
--- a/libgnucash/engine/qofquery.h
+++ b/libgnucash/engine/qofquery.h
@@ -368,13 +368,6 @@ void qof_query_set_max_results (QofQuery *q, int n);
*/
gboolean qof_query_equal (const QofQuery *q1, const QofQuery *q2);
-/** Log the Query
- *
- * \deprecated Do not call directly, use the standard log
- * module code: ::qof_log_set_level(QOF_MOD_QUERY, QOF_LOG_DEBUG);
- */
-void qof_query_print (QofQuery *query);
-
/** Return the type of data we're querying for */
/*@ dependent @*/
QofIdType qof_query_get_search_for (const QofQuery *q);
diff --git a/libgnucash/engine/test/test-gnc-uri-utils.c b/libgnucash/engine/test/test-gnc-uri-utils.c
index 2f4bbd8c5d..171fbdf28f 100644
--- a/libgnucash/engine/test/test-gnc-uri-utils.c
+++ b/libgnucash/engine/test/test-gnc-uri-utils.c
@@ -228,7 +228,7 @@ test_gnc_uri_get_components()
}
}
-/* TEST: gnc_uri_get_protocol */
+/* TEST: gnc_uri_get_scheme */
static void
test_gnc_uri_get_scheme()
{
@@ -291,7 +291,7 @@ test_gnc_uri_normalize_uri()
}
}
-/* TEST: gnc_uri_is_file_protocol */
+/* TEST: gnc_uri_is_file_scheme */
static void
test_gnc_uri_is_file_scheme()
{
commit d8ac86afd7f961fb22140ff7599d3e39b10ac66d
Author: Geert Janssens <geert at kobaltwit.be>
Date: Tue May 21 14:48:44 2024 +0200
Integrate callgrind documentation into Hacking
diff --git a/HACKING b/HACKING
index ccbea4bef5..52bae0a1ac 100644
--- a/HACKING
+++ b/HACKING
@@ -104,6 +104,50 @@ This file needs to be cleaned up in two ways:
2/ There are a bunch of suppressions which need to not be suppressions, but
instead just not be generated by valgrind.
+Using Callgrind with GnuCash
+----------------------------
+In order to debug with callgrind, you need to add a couple of code
+fragments around the section of code you are profiling. This is
+easiest if you can find the function that invokes the routine(s) you
+want to profile, add the following code around the function call of
+interest.
+
+Add the following to the start of the file:
+
+#include <valgrind/callgrind.h>
+
+Add the following to the start of the calling function:
+
+static GTimeVal start, end;
+
+Add the following just before the function of interest:
+
+g_print("Start timing.\n");
+g_get_current_time(&start);
+CALLGRIND_START_INSTRUMENTATION();
+CALLGRIND_TOGGLE_COLLECT();
+
+Add the following just after the function of interest:
+
+CALLGRIND_TOGGLE_COLLECT();
+CALLGRIND_STOP_INSTRUMENTATION();
+g_get_current_time(&end);
+if (start.tv_usec > end.tv_usec) {
+ end.tv_usec += 1000000;
+ end.tv_sec -= 1;
+}
+g_print("Callgrind enabled for %d.%6d seconds.\n",
+ (int)(end.tv_sec - start.tv_sec),
+ (int)(end.tv_usec - start.tv_usec));
+
+You will need to recompile, and then run the 'gnucash-valgrind'
+wrapper script instead of the normal 'gnucash' script.
+
+NOTE: Version 3.2 of valgrind has changed the above macros to no
+longer take an argument. In order to compile with this version of
+valgrind you will need to remove the trailing parentheses and
+semicolon.
+
Look up exported and imported symbols
-------------------------------------
diff --git a/libgnucash/doc/CMakeLists.txt b/libgnucash/doc/CMakeLists.txt
index 92fd714ff0..f02acbcf33 100644
--- a/libgnucash/doc/CMakeLists.txt
+++ b/libgnucash/doc/CMakeLists.txt
@@ -1,5 +1,4 @@
set(doc_FILES
- callgrind.txt
constderv.html
doxygen.cfg.in
doxygen_main_page.c
diff --git a/libgnucash/doc/callgrind.txt b/libgnucash/doc/callgrind.txt
deleted file mode 100644
index 118b196ccd..0000000000
--- a/libgnucash/doc/callgrind.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-In order to debug with callgrind, you need to add a couple of code
-fragments around the section of code you are profiling. This is
-easiest if you can find the function that invokes the routine(s) you
-want to profile, add the following code around the function call of
-interest.
-
-Add the following to the start of the file:
-
- #include <valgrind/callgrind.h>
-
-Add the following to the start of the calling function:
-
- static GTimeVal start, end;
-
-Add the following just before the function of interest:
-
- g_print("Start timing.\n");
- g_get_current_time(&start);
- CALLGRIND_START_INSTRUMENTATION();
- CALLGRIND_TOGGLE_COLLECT();
-
-Add the following just after the function of interest:
-
- CALLGRIND_TOGGLE_COLLECT();
- CALLGRIND_STOP_INSTRUMENTATION();
- g_get_current_time(&end);
- if (start.tv_usec > end.tv_usec) {
- end.tv_usec += 1000000;
- end.tv_sec -= 1;
- }
- g_print("Callgrind enabled for %d.%6d seconds.\n",
- (int)(end.tv_sec - start.tv_sec),
- (int)(end.tv_usec - start.tv_usec));
-
-You will need to recompile, and then run the 'gnucash-valgrind'
-wrapper script instead of the normal 'gnucash' script.
-
-NOTE: Version 3.2 of valgrind has changed the above macros to no
-longer take an argument. In order to compile with this version of
-valgrind you will need to remove the trailing parentheses and
-semicolon.
commit cf7ff07624975505cb4d32f3904d1e909a8cb001
Author: Geert Janssens <geert at kobaltwit.be>
Date: Tue May 21 14:41:30 2024 +0200
Move libgnucash/doc/xml to libgnucash/backend/xml/DTD
diff --git a/libgnucash/backend/xml/CMakeLists.txt b/libgnucash/backend/xml/CMakeLists.txt
index b21cf5d733..69d38af1b8 100644
--- a/libgnucash/backend/xml/CMakeLists.txt
+++ b/libgnucash/backend/xml/CMakeLists.txt
@@ -1,5 +1,6 @@
# CMakeLists.txt for libgnucash/backend/xml
+add_subdirectory(DTD)
add_subdirectory(test)
set (backend_xml_utils_noinst_HEADERS
@@ -72,7 +73,7 @@ set (backend_xml_utils_SOURCES
set_local_dist(backend_xml_DIST_local ${backend_xml_utils_SOURCES}
${backend_xml_utils_noinst_HEADERS} gnc-backend-xml.cpp CMakeLists.txt
)
-set(backend_xml_DIST ${backend_xml_DIST_local} ${test_backend_xml_DIST} PARENT_SCOPE)
+set(backend_xml_DIST ${backend_xml_DIST_local} ${test_backend_xml_DIST} ${backend_xml_DTD_DIST} PARENT_SCOPE)
# Add dependency on config.h
set_source_files_properties (${backend_xml_utils_SOURCES} PROPERTIES OBJECT_DEPENDS ${CONFIG_H})
diff --git a/libgnucash/doc/xml/CMakeLists.txt b/libgnucash/backend/xml/DTD/CMakeLists.txt
similarity index 72%
rename from libgnucash/doc/xml/CMakeLists.txt
rename to libgnucash/backend/xml/DTD/CMakeLists.txt
index 94d6fa5fe7..1966d0dd25 100644
--- a/libgnucash/doc/xml/CMakeLists.txt
+++ b/libgnucash/backend/xml/DTD/CMakeLists.txt
@@ -1,4 +1,4 @@
-set(doc_xml_FILES
+set(backend_xml_DTD_FILES
account-v2.dtd
commodity-v2.dtd
defaults-v1.dtd
@@ -12,4 +12,4 @@ set(doc_xml_FILES
types.dtd
)
-set_dist_list(doc_xml_DIST CMakeLists.txt ${doc_xml_FILES})
\ No newline at end of file
+set_dist_list(backend_xml_DTD_DIST CMakeLists.txt ${backend_xml_DTD_FILES})
diff --git a/libgnucash/doc/xml/README b/libgnucash/backend/xml/DTD/README
similarity index 100%
rename from libgnucash/doc/xml/README
rename to libgnucash/backend/xml/DTD/README
diff --git a/libgnucash/doc/xml/account-v2.dtd b/libgnucash/backend/xml/DTD/account-v2.dtd
similarity index 100%
rename from libgnucash/doc/xml/account-v2.dtd
rename to libgnucash/backend/xml/DTD/account-v2.dtd
diff --git a/libgnucash/doc/xml/commodity-v2.dtd b/libgnucash/backend/xml/DTD/commodity-v2.dtd
similarity index 100%
rename from libgnucash/doc/xml/commodity-v2.dtd
rename to libgnucash/backend/xml/DTD/commodity-v2.dtd
diff --git a/libgnucash/doc/xml/defaults-v1.dtd b/libgnucash/backend/xml/DTD/defaults-v1.dtd
similarity index 100%
rename from libgnucash/doc/xml/defaults-v1.dtd
rename to libgnucash/backend/xml/DTD/defaults-v1.dtd
diff --git a/libgnucash/doc/xml/gnucash-v2.rnc b/libgnucash/backend/xml/DTD/gnucash-v2.rnc
similarity index 100%
rename from libgnucash/doc/xml/gnucash-v2.rnc
rename to libgnucash/backend/xml/DTD/gnucash-v2.rnc
diff --git a/libgnucash/doc/xml/io-gncxml-version1.dtd b/libgnucash/backend/xml/DTD/io-gncxml-version1.dtd
similarity index 100%
rename from libgnucash/doc/xml/io-gncxml-version1.dtd
rename to libgnucash/backend/xml/DTD/io-gncxml-version1.dtd
diff --git a/libgnucash/doc/xml/io-gncxml-version2.dtd b/libgnucash/backend/xml/DTD/io-gncxml-version2.dtd
similarity index 100%
rename from libgnucash/doc/xml/io-gncxml-version2.dtd
rename to libgnucash/backend/xml/DTD/io-gncxml-version2.dtd
diff --git a/libgnucash/doc/xml/preferences-v1.dtd b/libgnucash/backend/xml/DTD/preferences-v1.dtd
similarity index 100%
rename from libgnucash/doc/xml/preferences-v1.dtd
rename to libgnucash/backend/xml/DTD/preferences-v1.dtd
diff --git a/libgnucash/doc/xml/prices-v1.dtd b/libgnucash/backend/xml/DTD/prices-v1.dtd
similarity index 100%
rename from libgnucash/doc/xml/prices-v1.dtd
rename to libgnucash/backend/xml/DTD/prices-v1.dtd
diff --git a/libgnucash/doc/xml/transactions-v2.dtd b/libgnucash/backend/xml/DTD/transactions-v2.dtd
similarity index 100%
rename from libgnucash/doc/xml/transactions-v2.dtd
rename to libgnucash/backend/xml/DTD/transactions-v2.dtd
diff --git a/libgnucash/doc/xml/types.dtd b/libgnucash/backend/xml/DTD/types.dtd
similarity index 100%
rename from libgnucash/doc/xml/types.dtd
rename to libgnucash/backend/xml/DTD/types.dtd
diff --git a/libgnucash/doc/CMakeLists.txt b/libgnucash/doc/CMakeLists.txt
index a28be64027..92fd714ff0 100644
--- a/libgnucash/doc/CMakeLists.txt
+++ b/libgnucash/doc/CMakeLists.txt
@@ -1,5 +1,3 @@
-add_subdirectory(xml)
-
set(doc_FILES
callgrind.txt
constderv.html
@@ -14,7 +12,7 @@ set(doc_FILES
)
set_local_dist(doc_DIST_local CMakeLists.txt ${doc_FILES})
-set(doc_DIST ${doc_DIST_local} ${doc_design_DIST} ${doc_xml_DIST} PARENT_SCOPE)
+set(doc_DIST ${doc_DIST_local} ${doc_design_DIST} PARENT_SCOPE)
find_program(DOXYGEN doxygen)
if (NOT ${DOXYGEN} STREQUAL "DOXYGEN-NOTFOUND")
commit da12a212c376e4d983aad270e7f0c84fe9b1642e
Author: Geert Janssens <geert at kobaltwit.be>
Date: Mon May 20 22:29:56 2024 +0200
Drop old migration script to split qof from engine
diff --git a/libgnucash/engine/xlate.pl b/libgnucash/engine/xlate.pl
deleted file mode 100755
index 68e3baa65e..0000000000
--- a/libgnucash/engine/xlate.pl
+++ /dev/null
@@ -1,272 +0,0 @@
-#! /usr/bin/perl
-## @file
-# @brief
-# FUNCTION: this utility script converts old code to the new
-# QOF routine names, and does other related cleanup
-#
-# USAGE: ls *.c *.h | ./xlate.pl ; make ; cvs commit
-#
-# AUTHOR: Linas Vepstas <linas at linas.org> June 2003
-# @author Linas Vepstas <linas at linas.org>
-# @date June 2003
-# @cond Perl
-
- at files = <STDIN>;
-
-# print @files;
-
-foreach (@files)
-{
- chop;
- $afile= $_;
- open (AF, $afile);
- open (OF, "> " . $afile . ".tmp");
-
- while (<AF>)
- {
-
- if (0) {
- s/GNCBook/QofBook/g;
- s/gnc_book_not_saved/qof_book_not_saved/g;
- s/gnc_book_get_guid/qof_book_get_guid/g;
- s/BookList/QofBookList/g;
- s/gnc_book_get_slots/qof_book_get_slots/g;
- s/gnc_book_set_guid/qof_book_set_guid/g;
- s/gnc_book_new/qof_book_new/g;
-
-
- s/GncObject_t/QofObject/g;
- s/gncObjectLookup/qof_object_lookup/g;
- s/gncObjectRegister/qof_object_register/g;
- s/gncObjectGetTypeLabel/qof_object_get_type_label/g;
- s/gncObjectRegisterBackend/qof_object_register_backend/g;
- s/gncObjectLookupBackend/qof_object_lookup_backend/g;
- s/gncObjectForeachBackend/qof_object_foreach_backend/g;
- s/gncObjectInitialize/qof_object_initialize/g;
-
- s/gncObjectShutdown/qof_object_shutdown/g;
- s/gncObjectBookBegin/qof_object_book_begin/g;
- s/gncObjectBookEnd/qof_object_book_end/g;
- s/gncObjectIsDirty/qof_object_is_dirty/g;
- s/gncObjectMarkClean/qof_object_mark_clean/g;
-
- s/gncObjectForeachType/qof_object_foreach_type/g;
- s/gncObjectForeach/qof_object_foreach/g;
- s/gncObjectPrintable/qof_object_printable/g;
-
- s/foreachTypeCB/QofForeachTypeCB/g;
- s/foreachBackendTypeCB/QofForeachBackendTypeCB/g;
-
- s/gncQueryStringPredicate/qof_query_string_predicate/g;
- s/gncQueryDatePredicate/qof_query_date_predicate/g;
- s/gncQueryNumericPredicate/qof_query_numeric_predicate/g;
- s/gncQueryGUIDPredicate/qof_query_guid_predicate/g;
- s/gncQueryInt32Predicate/qof_query_int32_predicate/g;
- s/gncQueryInt64Predicate/qof_query_int64_predicate/g;
- s/gncQueryDoublePredicate/qof_query_double_predicate/g;
- s/gncQueryBooleanPredicate/qof_query_boolean_predicate/g;
- s/gncQueryCharPredicate/qof_query_char_predicate/g;
- s/gncQueryKVPPredicate/qof_query_kvp_predicate/g;
- s/gncQueryCorePredicateFree/qof_query_core_predicate_free/g;
-
- s/COMPARE_LT/QOF_COMPARE_LT/g;
- s/COMPARE_LTE/QOF_COMPARE_LTE/g;
- s/COMPARE_EQUAL/QOF_COMPARE_EQUAL/g;
- s/COMPARE_GT/QOF_COMPARE_GT/g;
- s/COMPARE_GTE/QOF_COMPARE_GTE/g;
- s/COMPARE_NEQ/QOF_COMPARE_NEQ/g;
-
- s/STRING_MATCH_NORMAL/QOF_STRING_MATCH_NORMAL/g;
- s/STRING_MATCH_CASEINSENSITIVE/QOF_STRING_MATCH_CASEINSENSITIVE/g;
-
- s/DATE_MATCH_NORMAL/QOF_DATE_MATCH_NORMAL/g;
- s/DATE_MATCH_ROUNDED/QOF_DATE_MATCH_ROUNDED/g;
-
- s/NUMERIC_MATCH_ANY/QOF_NUMERIC_MATCH_ANY/g;
- s/NUMERIC_MATCH_CREDIT/QOF_NUMERIC_MATCH_CREDIT/g;
- s/NUMERIC_MATCH_DEBIT/QOF_NUMERIC_MATCH_DEBIT/g;
-
- s/GUID_MATCH_ANY/QOF_GUID_MATCH_ANY/g;
- s/GUID_MATCH_NONE/QOF_GUID_MATCH_NONE/g;
- s/GUID_MATCH_NULL/QOF_GUID_MATCH_NULL/g;
- s/GUID_MATCH_ALL/QOF_GUID_MATCH_ALL/g;
- s/GUID_MATCH_LIST_ANY/QOF_GUID_MATCH_LIST_ANY/g;
-
- s/CHAR_MATCH_ANY/QOF_CHAR_MATCH_ANY/g;
- s/CHAR_MATCH_NONE/QOF_CHAR_MATCH_NONE/g;
-
- s/char_match_t/QofCharMatch/g;
- s/guid_match_t/QofGuidMatch/g;
- s/numeric_match_t/QofNumericMatch/g;
- s/date_match_t/QofDateMatch/g;
- s/string_match_t/QofStringMatch/g;
- s/query_compare_t/QofQueryCompare/g;
-
- s/gncQueryCoreInit/qof_query_core_init/g;
- s/gncQueryCoreShutdown/qof_query_core_shutdown/g;
- s/gncQueryCoreGetPredicate/qof_query_core_get_predicate/g;
- s/gncQueryCoreGetCompare/qof_query_core_get_compare/g;
-
- s/gncQueryCorePredicateEqual/qof_query_core_predicate_equal/g;
-
- s/QUERY_AND/QOF_QUERY_AND/g;
- s/QUERY_OR/QOF_QUERY_OR/g;
- s/QUERY_NAND/QOF_QUERY_NAND/g;
- s/QUERY_NOR/QOF_QUERY_NOR/g;
- s/QUERY_XOR/QOF_QUERY_XOR/g;
- s/QUERY_PARAM_BOOK/QOF_PARAM_BOOK/g;
- s/QUERY_PARAM_GUID/QOF_PARAM_GUID/g;
- s/QUERY_PARAM_ACTIVE/QOF_PARAM_ACTIVE/g;
-
- s/QUERYCORE_INT64/QOF_QUERYCORE_INT64/g;
- s/QUERYCORE_STRING/QOF_QUERYCORE_STRING/g;
- s/QUERYCORE_GUID/QOF_QUERYCORE_GUID/g;
- s/QUERYCORE_DATE/QOF_QUERYCORE_DATE/g;
- s/QUERYCORE_BOOLEAN/QOF_QUERYCORE_BOOLEAN/g;
- s/QUERYCORE_NUMERIC/QOF_QUERYCORE_NUMERIC/g;
-
- s/gncQueryBuildParamList/qof_query_build_param_list/g;
- s/gncQueryCreateFor/qof_query_create_for/g;
- s/gncQueryCreate/qof_query_create/g;
- s/gncQueryDestroy/qof_query_destroy/g;
- s/gncQuerySearchFor/qof_query_search_for/g;
- s/gncQuerySetBook/qof_query_set_book/g;
- s/gncQueryAddTerm/qof_query_add_term/g;
- s/gncQueryAddGUIDMatch/qof_query_add_guid_match/g;
- s/gncQueryAddGUIDListMatch/qof_query_add_guid_list_match/g;
- s/gncQueryAddBooleanMatch/qof_query_add_boolean_match/g;
- s/gncQueryRun/qof_query_run/g;
- s/gncQueryLastRun/qof_query_last_run/g;
- s/gncQueryClear/qof_query_clear/g;
- s/gncQueryPurgeTerms/qof_query_purge_terms/g;
- s/gncQueryHasTerms/qof_query_has_terms/g;
- s/gncQueryNumTerms/qof_query_num_terms/g;
- s/gncQueryHasTermType/qof_query_has_term_type/g;
- s/gncQueryCopy/qof_query_copy/g;
- s/gncQueryInvert/qof_query_invert/g;
- s/gncQueryMerge/qof_query_merge/g;
- s/gncQueryMergeInPlace/qof_query_merges_ins_place/g;
- s/gncQuerySetSortOrder/qof_query_set_sort_order/g;
- s/gncQuerySetSortOptions/qof_query_set_sort_options/g;
- s/gncQuerySetSortIncreasing/qof_query_set_sort_increasing/g;
- s/gncQuerySetMaxResults/qof_query_set_max_results/g;
- s/gncQueryEqual/qof_query_equal/g;
- s/gncQueryPrint/qof_query_print/g;
- s/gncQueryGetSearchFor/qof_query_get_search_for/g;
- s/gncQueryGetBooks/qof_query_get_books/g;
-
- s/gncQueryNewInit/qof_query_new_init/g;
- s/gncQueryNewShutdown/qof_query_new_shutdown/g;
- s/gncQueryGetMaxResults/qof_query_get_max_results/g;
- s/gncQueryGetTerms/qof_query_get_terms/g;
- s/gncQueryTermGetParamPath/qof_query_term_get_param_path/g;
- s/gncQueryTermGetPredData/qof_query_term_get_pred_data/g;
- s/gncQueryTermIsInverted/qof_query_term_is_inverted/g;
- s/gncQueryGetSorts/qof_query_get_sorts/g;
- s/gncQuerySortGetParamPath/qof_query_sort_get_param_path/g;
- s/gncQuerySortGetSortOptions/qof_query_sort_get_sort_options/g;
- s/gncQuerySortGetIncreasing/qof_query_sort_get_increasing/g;
-
- s/QuerySort/QofSortFunc/g;
- s/QueryTerm_t/QofQueryTerm/g;
- s/SortFunc_t/QofQuerySort/g;
-
- s/querynew_s/_QofQuery/g;
- s/QueryNew/QofQuery/g;
- s/QueryOp/QofQueryOp/g;
- s/query_new_term/_QofQueryTerm/g;
- s/query_new_sort/_QofQuerySort/g;
-
- s/query_object_def/_QofParam/g;
- s/QueryObjectDef/QofParam/g;
-
- s/QueryAccess/QofAccessFunc/g;
-
- s/gncQueryObjectRegister/qof_class_register/g;
- s/gncQueryObjectParameterType/qof_class_get_parameter_type/g;
- s/gncQueryObjectGetParameterGetter/qof_class_get_parameter_getter/g;
- s/gncQueryObjectGetParameter/qof_class_get_parameter/g;
- s/gncQueryObjectInit/qof_class_init/g;
- s/gncQueryObjectShutdown/qof_class_shutdown/g;
- s/gncQueryObjectDefaultSort/qof_class_get_default_sort/g;
-
- s/xaccGUIDNULL/guid_null/g;
- s/xaccGUIDMalloc/guid_malloc/g;
- s/xaccGUIDFree/guid_free/g;
-
- s/GNCIdTypeConst/QofIdTypeConst/g;
- s/GNCIdType/QofIdType/g;
- s/GNCEntityTable/QofInstanceTable/g;
- s/xaccGUIDTypeEntityTable/qof_guid_type/g;
-
- s/xaccEntityTableNew/qof_instance_new/g;
- s/xaccEntityTableDestroy/qof_instance_destroy/g;
- s/xaccGUIDNewEntityTable/qof_instance_guid_new/g;
- s/xaccLookupEntity/qof_instance_lookup/g;
- s/xaccStoreEntity/qof_instance_store/g;
- s/xaccRemoveEntity/qof_instance_remove/g;
- s/xaccForeachEntity/qof_instance_foreach/g;
-
- s/foreachObjectCB/QofInstanceForeachCB/g;
- s/GNC_OBJECT_VERSION/QOF_OBJECT_VERSION/g;
-
- s/GNCSession/QofSession/g;
- s/gnc_session/qof_session/g;
- s/GNCPercentageFunc/QofPercentageFunc/g;
- s/gnc_get_current_session/qof_session_get_current_session/g;
- s/gnc_set_current_session/qof_session_set_current_session/g;
-
- s/ Backend/ QofBackend/g;
- s/\(Backend/\(QofBackend/g;
- s/GNCBackendError/QofBackendError/g;
- s/GNCBePercentageFunc/QofBePercentageFunc/g;
- s/xaccBackendSetError/qof_backend_set_error/g;
- s/xaccBackendGetError/qof_backend_get_error/g;
- s/xaccBackendSetMessage/qof_backend_set_message/g;
- s/xaccBackendGetMessage/qof_backend_get_message/g;
- s/xaccInitBackend/qof_backend_init/g;
-
- s/GNCId\.h/qofid\.h/g;
- s/gncObject\.h/qofobject\.h/g;
- s/QueryCore\.h/qofquerycore\.h/g;
- s/QofQuery\.h/qofquery\.h/g;
- s/QueryObject\.h/qofqueryobject\.h/g;
-
-
- s/kvp_frame /KvpFrame /g;
- s/kvp_frame* /KvpFrame* /g;
- s/kvp_value /KvpValue /g;
- s/kvp_value* /KvpValue* /g;
- s/kvp_value_t/KvpValueType/g;
-
- s/QofQof/Qof/g;
- s/QOF_QOF/QOF/g;
-
- s/getDateFormatString/qof_date_format_get_string/g;
- s/getDateTextFormatString/qof_date_format_get_format/g;
- s/getDateFormat/qof_date_format_get/g;
- s/setDateFormat/qof_date_format_set/g;
- s/DateFormat/QofDateFormat/g;
- s/printDateSecs/qof_print_date_buff/g;
- s/printDate/qof_print_date_dmy_buff/g;
- s/printGDate/qof_print_gdate/g;
- s/xaccPrintDateSecs/qof_print_date/g;
- s/scanDate/qof_scan_date/g;
- s/DATE_FORMAT_US/QOF_DATE_FORMAT_US/g;
- s/DATE_FORMAT_UK/QOF_DATE_FORMAT_UK/g;
- s/DATE_FORMAT_CE/QOF_DATE_FORMAT_CE/g;
- s/DATE_FORMAT_ISO/QOF_DATE_FORMAT_ISO/g;
- s/DATE_FORMAT_LOCALE/QOF_DATE_FORMAT_LOCALE/g;
- s/DATE_FORMAT_CUSTOM/QOF_DATE_FORMAT_CUSTOM/g;
-
- }
-
- print OF $_;
- }
- close OF;
- close AF;
-
- $rn = "mv " . $afile . ".tmp " . $afile;
- system ($rn);
-}
-## @endcond Perl
commit 891b921c811f32e214fe9fc1a87e392b58ed7757
Author: Geert Janssens <geert at kobaltwit.be>
Date: Mon May 20 20:30:45 2024 +0200
Update doxygen.cnf file to more recent release
diff --git a/libgnucash/doc/doxygen.cfg.in b/libgnucash/doc/doxygen.cfg.in
index 91a92b4290..156f491d61 100644
--- a/libgnucash/doc/doxygen.cfg.in
+++ b/libgnucash/doc/doxygen.cfg.in
@@ -1,110 +1,151 @@
-# Doxyfile 1.8.3.1
+# Doxyfile 1.9.7
# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project.
#
-# All text after a hash (#) is considered a comment and will be ignored.
+# All text after a double hash (##) is considered a comment and is placed in
+# front of the TAG it is preceding.
+#
+# All text after a single hash (#) is considered a comment and will be ignored.
# The format is:
-# TAG = value [value, ...]
-# For lists items can also be appended using:
-# TAG += value [value, ...]
-# Values that contain spaces should be placed between quotes (" ").
+# TAG = value [value, ...]
+# For lists, items can also be appended using:
+# TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (\" \").
+#
+# Note:
+#
+# Use doxygen to compare the used configuration file with the template
+# configuration file:
+# doxygen -x [configFile]
+# Use doxygen to compare the used configuration file with the template
+# configuration file without replacing the environment variables or CMake type
+# replacement variables:
+# doxygen -x_noenv [configFile]
#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
-# This tag specifies the encoding used for all characters in the config file
-# that follow. The default is UTF-8 which is also the encoding used for all
+# This tag specifies the encoding used for all characters in the configuration
+# file that follow. The default is UTF-8 which is also the encoding used for all
# text before the first occurrence of this tag. Doxygen uses libiconv (or the
# iconv built into libc) for the transcoding. See
-# https://www.gnu.org/software/libiconv for the list of possible encodings.
+# https://www.gnu.org/software/libiconv/ for the list of possible encodings.
+# The default value is: UTF-8.
DOXYFILE_ENCODING = UTF-8
-# The PROJECT_NAME tag is a single word (or sequence of words) that should
-# identify the project. Note that if you do not use Doxywizard you need
-# to put quotes around the project name if it contains spaces.
+# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by
+# double-quotes, unless you are using Doxywizard) that should identify the
+# project for which the documentation is generated. This name is used in the
+# title of most generated pages and in a few other places.
+# The default value is: My Project.
-PROJECT_NAME = GnuCash
+PROJECT_NAME = ${PACKAGE_NAME}
-# The PROJECT_NUMBER tag can be used to enter a project or revision number.
-# This could be handy for archiving the generated documentation or
-# if some version control system is used.
+# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
+# could be handy for archiving the generated documentation or if some version
+# control system is used.
-PROJECT_NUMBER = @VERSION@
+PROJECT_NUMBER = ${PROJECT_VERSION}
# Using the PROJECT_BRIEF tag one can provide an optional one line description
-# for a project that appears at the top of each page and should give viewer
-# a quick idea about the purpose of the project. Keep the description short.
+# for a project that appears at the top of each page and should give viewer a
+# quick idea about the purpose of the project. Keep the description short.
PROJECT_BRIEF =
-# With the PROJECT_LOGO tag one can specify an logo or icon that is
-# included in the documentation. The maximum height of the logo should not
-# exceed 55 pixels and the maximum width should not exceed 200 pixels.
-# Doxygen will copy the logo to the output directory.
+# With the PROJECT_LOGO tag one can specify a logo or an icon that is included
+# in the documentation. The maximum height of the logo should not exceed 55
+# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
+# the logo to the output directory.
PROJECT_LOGO =
-# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
-# base path where the generated documentation will be put.
-# If a relative path is entered, it will be relative to the location
-# where doxygen was started. If left blank the current directory will be used.
+# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
+# into which the generated documentation will be written. If a relative path is
+# entered, it will be relative to the location where doxygen was started. If
+# left blank the current directory will be used.
OUTPUT_DIRECTORY =
-# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
-# 4096 sub-directories (in 2 levels) under the output directory of each output
-# format and will distribute the generated files over these directories.
-# Enabling this option can be useful when feeding doxygen a huge amount of
-# source files, where putting all generated files in the same directory would
-# otherwise cause performance problems for the file system.
+# If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096
+# sub-directories (in 2 levels) under the output directory of each output format
+# and will distribute the generated files over these directories. Enabling this
+# option can be useful when feeding doxygen a huge amount of source files, where
+# putting all generated files in the same directory would otherwise causes
+# performance problems for the file system. Adapt CREATE_SUBDIRS_LEVEL to
+# control the number of sub-directories.
+# The default value is: NO.
CREATE_SUBDIRS = NO
+# Controls the number of sub-directories that will be created when
+# CREATE_SUBDIRS tag is set to YES. Level 0 represents 16 directories, and every
+# level increment doubles the number of directories, resulting in 4096
+# directories at level 8 which is the default and also the maximum value. The
+# sub-directories are organized in 2 levels, the first level always has a fixed
+# number of 16 directories.
+# Minimum value: 0, maximum value: 8, default value: 8.
+# This tag requires that the tag CREATE_SUBDIRS is set to YES.
+
+CREATE_SUBDIRS_LEVEL = 8
+
+# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII
+# characters to appear in the names of generated files. If set to NO, non-ASCII
+# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode
+# U+3044.
+# The default value is: NO.
+
+ALLOW_UNICODE_NAMES = NO
+
# The OUTPUT_LANGUAGE tag is used to specify the language in which all
# documentation generated by doxygen is written. Doxygen will use this
# information to generate all constant output in the proper language.
-# The default language is English, other supported languages are:
-# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional,
-# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German,
-# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English
-# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian,
-# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak,
-# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese.
+# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Bulgarian,
+# Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch, English
+# (United States), Esperanto, Farsi (Persian), Finnish, French, German, Greek,
+# Hindi, Hungarian, Indonesian, Italian, Japanese, Japanese-en (Japanese with
+# English messages), Korean, Korean-en (Korean with English messages), Latvian,
+# Lithuanian, Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese,
+# Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish,
+# Swedish, Turkish, Ukrainian and Vietnamese.
+# The default value is: English.
OUTPUT_LANGUAGE = English
-# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
-# include brief member descriptions after the members that are listed in
-# the file and class documentation (similar to JavaDoc).
-# Set to NO to disable this.
+# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member
+# descriptions after the members that are listed in the file and class
+# documentation (similar to Javadoc). Set to NO to disable this.
+# The default value is: YES.
BRIEF_MEMBER_DESC = YES
-# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
-# the brief description of a member or function before the detailed description.
-# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
+# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief
+# description of a member or function before the detailed description
+#
+# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
# brief descriptions will be completely suppressed.
+# The default value is: YES.
REPEAT_BRIEF = YES
-# This tag implements a quasi-intelligent brief description abbreviator
-# that is used to form the text in various listings. Each string
-# in this list, if found as the leading text of the brief description, will be
-# stripped from the text and the result after processing the whole list, is
-# used as the annotated text. Otherwise, the brief description is used as-is.
-# If left blank, the following values are used ("$name" is automatically
-# replaced with the name of the entity): "The $name class" "The $name widget"
-# "The $name file" "is" "provides" "specifies" "contains"
-# "represents" "a" "an" "the"
+# This tag implements a quasi-intelligent brief description abbreviator that is
+# used to form the text in various listings. Each string in this list, if found
+# as the leading text of the brief description, will be stripped from the text
+# and the result, after processing the whole list, is used as the annotated
+# text. Otherwise, the brief description is used as-is. If left blank, the
+# following values are used ($name is automatically replaced with the name of
+# the entity):The $name class, The $name widget, The $name file, is, provides,
+# specifies, contains, represents, a, an and the.
ABBREVIATE_BRIEF =
# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
-# Doxygen will generate a detailed section even if there is only a brief
+# doxygen will generate a detailed section even if there is only a brief
# description.
+# The default value is: NO.
ALWAYS_DETAILED_SEC = NO
@@ -112,545 +153,785 @@ ALWAYS_DETAILED_SEC = NO
# inherited members of a class in the documentation of that class as if those
# members were ordinary class members. Constructors, destructors and assignment
# operators of the base classes will not be shown.
+# The default value is: NO.
INLINE_INHERITED_MEMB = NO
-# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
-# path before files name in the file list and in the header files. If set
-# to NO the shortest path that makes the file name unique will be used.
+# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path
+# before files name in the file list and in the header files. If set to NO the
+# shortest path that makes the file name unique will be used
+# The default value is: YES.
FULL_PATH_NAMES = NO
-# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
-# can be used to strip a user-defined part of the path. Stripping is
-# only done if one of the specified strings matches the left-hand part of
-# the path. The tag can be used to show relative paths in the file list.
-# If left blank the directory from which doxygen is run is used as the
-# path to strip. Note that you specify absolute paths here, but also
-# relative paths, which will be relative from the directory where doxygen is
-# started.
+# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
+# Stripping is only done if one of the specified strings matches the left-hand
+# part of the path. The tag can be used to show relative paths in the file list.
+# If left blank the directory from which doxygen is run is used as the path to
+# strip.
+#
+# Note that you can specify absolute paths here, but also relative paths, which
+# will be relative from the directory where doxygen is started.
+# This tag requires that the tag FULL_PATH_NAMES is set to YES.
STRIP_FROM_PATH =
-# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of
-# the path mentioned in the documentation of a class, which tells
-# the reader which header file to include in order to use a class.
-# If left blank only the name of the header file containing the class
-# definition is used. Otherwise one should specify the include paths that
-# are normally passed to the compiler using the -I flag.
+# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
+# path mentioned in the documentation of a class, which tells the reader which
+# header file to include in order to use a class. If left blank only the name of
+# the header file containing the class definition is used. Otherwise one should
+# specify the list of include paths that are normally passed to the compiler
+# using the -I flag.
STRIP_FROM_INC_PATH =
-# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter
-# (but less readable) file names. This can be useful if your file system
-# doesn't support long names like on DOS, Mac, or CD-ROM.
+# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but
+# less readable) file names. This can be useful is your file systems doesn't
+# support long names like on DOS, Mac, or CD-ROM.
+# The default value is: NO.
SHORT_NAMES = NO
-# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
-# will interpret the first line (until the first dot) of a JavaDoc-style
-# comment as the brief description. If set to NO, the JavaDoc
-# comments will behave just like regular Qt-style comments
-# (thus requiring an explicit @brief command for a brief description.)
+# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the
+# first line (until the first dot) of a Javadoc-style comment as the brief
+# description. If set to NO, the Javadoc-style will behave just like regular Qt-
+# style comments (thus requiring an explicit @brief command for a brief
+# description.)
+# The default value is: NO.
JAVADOC_AUTOBRIEF = YES
-# If the QT_AUTOBRIEF tag is set to YES then Doxygen will
-# interpret the first line (until the first dot) of a Qt-style
-# comment as the brief description. If set to NO, the comments
-# will behave just like regular Qt-style comments (thus requiring
-# an explicit \brief command for a brief description.)
+# If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line
+# such as
+# /***************
+# as being the beginning of a Javadoc-style comment "banner". If set to NO, the
+# Javadoc-style will behave just like regular comments and it will not be
+# interpreted by doxygen.
+# The default value is: NO.
+
+JAVADOC_BANNER = NO
+
+# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first
+# line (until the first dot) of a Qt-style comment as the brief description. If
+# set to NO, the Qt-style will behave just like regular Qt-style comments (thus
+# requiring an explicit \brief command for a brief description.)
+# The default value is: NO.
QT_AUTOBRIEF = NO
-# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
-# treat a multi-line C++ special comment block (i.e. a block of //! or ///
-# comments) as a brief description. This used to be the default behaviour.
-# The new default is to treat a multi-line C++ comment block as a detailed
-# description. Set this tag to YES if you prefer the old behaviour instead.
+# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a
+# multi-line C++ special comment block (i.e. a block of //! or /// comments) as
+# a brief description. This used to be the default behavior. The new default is
+# to treat a multi-line C++ comment block as a detailed description. Set this
+# tag to YES if you prefer the old behavior instead.
+#
+# Note that setting this tag to YES also means that rational rose comments are
+# not recognized any more.
+# The default value is: NO.
MULTILINE_CPP_IS_BRIEF = NO
-# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
-# member inherits the documentation from any documented member that it
-# re-implements.
+# By default Python docstrings are displayed as preformatted text and doxygen's
+# special commands cannot be used. By setting PYTHON_DOCSTRING to NO the
+# doxygen's special commands can be used and the contents of the docstring
+# documentation blocks is shown as doxygen documentation.
+# The default value is: YES.
+
+PYTHON_DOCSTRING = YES
+
+# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the
+# documentation from any documented member that it re-implements.
+# The default value is: YES.
INHERIT_DOCS = YES
-# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce
-# a new page for each member. If set to NO, the documentation of a member will
-# be part of the file/class/namespace that contains it.
+# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new
+# page for each member. If set to NO, the documentation of a member will be part
+# of the file/class/namespace that contains it.
+# The default value is: NO.
SEPARATE_MEMBER_PAGES = NO
-# The TAB_SIZE tag can be used to set the number of spaces in a tab.
-# Doxygen uses this value to replace tabs by spaces in code fragments.
+# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen
+# uses this value to replace tabs by spaces in code fragments.
+# Minimum value: 1, maximum value: 16, default value: 4.
TAB_SIZE = 4
-# This tag can be used to specify a number of aliases that acts
-# as commands in the documentation. An alias has the form "name=value".
-# For example adding "sideeffect=\par Side Effects:\n" will allow you to
-# put the command \sideeffect (or @sideeffect) in the documentation, which
-# will result in a user-defined paragraph with heading "Side Effects:".
-# You can put \n's in the value part of an alias to insert newlines.
+# This tag can be used to specify a number of aliases that act as commands in
+# the documentation. An alias has the form:
+# name=value
+# For example adding
+# "sideeffect=@par Side Effects:^^"
+# will allow you to put the command \sideeffect (or @sideeffect) in the
+# documentation, which will result in a user-defined paragraph with heading
+# "Side Effects:". Note that you cannot put \n's in the value part of an alias
+# to insert newlines (in the resulting output). You can put ^^ in the value part
+# of an alias to insert a newline as if a physical newline was in the original
+# file. When you need a literal { or } or , in the value part of an alias you
+# have to escape them by means of a backslash (\), this can lead to conflicts
+# with the commands \{ and \} for these it is advised to use the version @{ and
+# @} or use a double escape (\\{ and \\})
ALIASES =
-# This tag can be used to specify a number of word-keyword mappings (TCL only).
-# A mapping has the form "name=value". For example adding
-# "class=itcl::class" will allow you to use the command class in the
-# itcl::class meaning.
-
-TCL_SUBST =
-
-# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
-# sources only. Doxygen will then generate output that is more tailored for C.
-# For instance, some of the names that are used will be different. The list
-# of all members will be omitted, etc.
+# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
+# only. Doxygen will then generate output that is more tailored for C. For
+# instance, some of the names that are used will be different. The list of all
+# members will be omitted, etc.
+# The default value is: NO.
OPTIMIZE_OUTPUT_FOR_C = YES
-# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java
-# sources only. Doxygen will then generate output that is more tailored for
-# Java. For instance, namespaces will be presented as packages, qualified
-# scopes will look different, etc.
+# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
+# Python sources only. Doxygen will then generate output that is more tailored
+# for that language. For instance, namespaces will be presented as packages,
+# qualified scopes will look different, etc.
+# The default value is: NO.
OPTIMIZE_OUTPUT_JAVA = NO
# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran
-# sources only. Doxygen will then generate output that is more tailored for
-# Fortran.
+# sources. Doxygen will then generate output that is tailored for Fortran.
+# The default value is: NO.
OPTIMIZE_FOR_FORTRAN = NO
# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL
-# sources. Doxygen will then generate output that is tailored for
-# VHDL.
+# sources. Doxygen will then generate output that is tailored for VHDL.
+# The default value is: NO.
OPTIMIZE_OUTPUT_VHDL = NO
+# Set the OPTIMIZE_OUTPUT_SLICE tag to YES if your project consists of Slice
+# sources only. Doxygen will then generate output that is more tailored for that
+# language. For instance, namespaces will be presented as modules, types will be
+# separated into more groups, etc.
+# The default value is: NO.
+
+OPTIMIZE_OUTPUT_SLICE = NO
+
# Doxygen selects the parser to use depending on the extension of the files it
# parses. With this tag you can assign which parser to use for a given
# extension. Doxygen has a built-in mapping, but you can override or extend it
-# using this tag. The format is ext=language, where ext is a file extension,
-# and language is one of the parsers supported by doxygen: IDL, Java,
-# Javascript, CSharp, C, C++, D, PHP, Objective-C, Python, Fortran, VHDL, C,
-# C++. For instance to make doxygen treat .inc files as Fortran files (default
-# is PHP), and .f files as C (default is Fortran), use: inc=Fortran f=C. Note
-# that for custom extensions you also need to set FILE_PATTERNS otherwise the
-# files are not read by doxygen.
+# using this tag. The format is ext=language, where ext is a file extension, and
+# language is one of the parsers supported by doxygen: IDL, Java, JavaScript,
+# Csharp (C#), C, C++, Lex, D, PHP, md (Markdown), Objective-C, Python, Slice,
+# VHDL, Fortran (fixed format Fortran: FortranFixed, free formatted Fortran:
+# FortranFree, unknown formatted Fortran: Fortran. In the later case the parser
+# tries to guess whether the code is fixed or free formatted code, this is the
+# default for Fortran type files). For instance to make doxygen treat .inc files
+# as Fortran files (default is PHP), and .f files as C (default is Fortran),
+# use: inc=Fortran f=C.
+#
+# Note: For files without extension you can use no_extension as a placeholder.
+#
+# Note that for custom extensions you also need to set FILE_PATTERNS otherwise
+# the files are not read by doxygen. When specifying no_extension you should add
+# * to the FILE_PATTERNS.
+#
+# Note see also the list of default file extension mappings.
EXTENSION_MAPPING = pl=python
-# If MARKDOWN_SUPPORT is enabled (the default) then doxygen pre-processes all
-# comments according to the Markdown format, which allows for more readable
-# documentation. See http://daringfireball.net/projects/markdown/ for details.
-# The output of markdown processing is further processed by doxygen, so you
-# can mix doxygen, HTML, and XML commands with Markdown formatting.
-# Disable only in case of backward compatibilities issues.
+# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments
+# according to the Markdown format, which allows for more readable
+# documentation. See https://daringfireball.net/projects/markdown/ for details.
+# The output of markdown processing is further processed by doxygen, so you can
+# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in
+# case of backward compatibilities issues.
+# The default value is: YES.
MARKDOWN_SUPPORT = YES
-# When enabled doxygen tries to link words that correspond to documented classes,
-# or namespaces to their corresponding documentation. Such a link can be
-# prevented in individual cases by by putting a % sign in front of the word or
+# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up
+# to that level are automatically included in the table of contents, even if
+# they do not have an id attribute.
+# Note: This feature currently applies only to Markdown headings.
+# Minimum value: 0, maximum value: 99, default value: 5.
+# This tag requires that the tag MARKDOWN_SUPPORT is set to YES.
+
+TOC_INCLUDE_HEADINGS = 5
+
+# The MARKDOWN_ID_STYLE tag can be used to specify the algorithm used to
+# generate identifiers for the Markdown headings. Note: Every identifier is
+# unique.
+# Possible values are: DOXYGEN Use a fixed 'autotoc_md' string followed by a
+# sequence number starting at 0. and GITHUB Use the lower case version of title
+# with any whitespace replaced by '-' and punctations characters removed..
+# The default value is: DOXYGEN.
+# This tag requires that the tag MARKDOWN_SUPPORT is set to YES.
+
+MARKDOWN_ID_STYLE = DOXYGEN
+
+# When enabled doxygen tries to link words that correspond to documented
+# classes, or namespaces to their corresponding documentation. Such a link can
+# be prevented in individual cases by putting a % sign in front of the word or
# globally by setting AUTOLINK_SUPPORT to NO.
+# The default value is: YES.
AUTOLINK_SUPPORT = YES
# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
-# to include (a tag file for) the STL sources as input, then you should
-# set this tag to YES in order to let doxygen match functions declarations and
-# definitions whose arguments contain STL classes (e.g. func(std::string); v.s.
-# func(std::string) {}). This also makes the inheritance and collaboration
+# to include (a tag file for) the STL sources as input, then you should set this
+# tag to YES in order to let doxygen match functions declarations and
+# definitions whose arguments contain STL classes (e.g. func(std::string);
+# versus func(std::string) {}). This also make the inheritance and collaboration
# diagrams that involve STL classes more complete and accurate.
+# The default value is: NO.
BUILTIN_STL_SUPPORT = YES
# If you use Microsoft's C++/CLI language, you should set this option to YES to
# enable parsing support.
+# The default value is: NO.
CPP_CLI_SUPPORT = NO
-# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only.
-# Doxygen will parse them like normal C++ but will assume all classes use public
-# instead of private inheritance when no explicit protection keyword is present.
+# Set the SIP_SUPPORT tag to YES if your project consists of sip (see:
+# https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen
+# will parse them like normal C++ but will assume all classes use public instead
+# of private inheritance when no explicit protection keyword is present.
+# The default value is: NO.
SIP_SUPPORT = NO
# For Microsoft's IDL there are propget and propput attributes to indicate
-# getter and setter methods for a property. Setting this option to YES (the
-# default) will make doxygen replace the get and set methods by a property in
-# the documentation. This will only work if the methods are indeed getting or
-# setting a simple type. If this is not the case, or you want to show the
-# methods anyway, you should set this option to NO.
+# getter and setter methods for a property. Setting this option to YES will make
+# doxygen to replace the get and set methods by a property in the documentation.
+# This will only work if the methods are indeed getting or setting a simple
+# type. If this is not the case, or you want to show the methods anyway, you
+# should set this option to NO.
+# The default value is: YES.
IDL_PROPERTY_SUPPORT = YES
# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
-# tag is set to YES, then doxygen will reuse the documentation of the first
+# tag is set to YES then doxygen will reuse the documentation of the first
# member in the group (if any) for the other members of the group. By default
# all members of a group must be documented explicitly.
+# The default value is: NO.
DISTRIBUTE_GROUP_DOC = NO
-# Set the SUBGROUPING tag to YES (the default) to allow class member groups of
-# the same type (for instance a group of public functions) to be put as a
-# subgroup of that type (e.g. under the Public Functions section). Set it to
-# NO to prevent subgrouping. Alternatively, this can be done per class using
-# the \nosubgrouping command.
+# If one adds a struct or class to a group and this option is enabled, then also
+# any nested class or struct is added to the same group. By default this option
+# is disabled and one has to add nested compounds explicitly via \ingroup.
+# The default value is: NO.
+
+GROUP_NESTED_COMPOUNDS = NO
+
+# Set the SUBGROUPING tag to YES to allow class member groups of the same type
+# (for instance a group of public functions) to be put as a subgroup of that
+# type (e.g. under the Public Functions section). Set it to NO to prevent
+# subgrouping. Alternatively, this can be done per class using the
+# \nosubgrouping command.
+# The default value is: YES.
SUBGROUPING = YES
-# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and
-# unions are shown inside the group in which they are included (e.g. using
-# @ingroup) instead of on a separate page (for HTML and Man pages) or
-# section (for LaTeX and RTF).
+# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions
+# are shown inside the group in which they are included (e.g. using \ingroup)
+# instead of on a separate page (for HTML and Man pages) or section (for LaTeX
+# and RTF).
+#
+# Note that this feature does not work in combination with
+# SEPARATE_MEMBER_PAGES.
+# The default value is: NO.
INLINE_GROUPED_CLASSES = NO
-# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and
-# unions with only public data fields will be shown inline in the documentation
-# of the scope in which they are defined (i.e. file, namespace, or group
-# documentation), provided this scope is documented. If set to NO (the default),
-# structs, classes, and unions are shown on a separate page (for HTML and Man
-# pages) or section (for LaTeX and RTF).
+# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions
+# with only public data fields or simple typedef fields will be shown inline in
+# the documentation of the scope in which they are defined (i.e. file,
+# namespace, or group documentation), provided this scope is documented. If set
+# to NO, structs, classes, and unions are shown on a separate page (for HTML and
+# Man pages) or section (for LaTeX and RTF).
+# The default value is: NO.
INLINE_SIMPLE_STRUCTS = NO
-# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum
-# is documented as struct, union, or enum with the name of the typedef. So
+# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or
+# enum is documented as struct, union, or enum with the name of the typedef. So
# typedef struct TypeS {} TypeT, will appear in the documentation as a struct
# with name TypeT. When disabled the typedef will appear as a member of a file,
-# namespace, or class. And the struct will be named TypeS. This can typically
-# be useful for C code in case the coding convention dictates that all compound
+# namespace, or class. And the struct will be named TypeS. This can typically be
+# useful for C code in case the coding convention dictates that all compound
# types are typedef'ed and only the typedef is referenced, never the tag name.
+# The default value is: NO.
-TYPEDEF_HIDES_STRUCT = NO
+TYPEDEF_HIDES_STRUCT = YES
-# Similar to the SYMBOL_CACHE_SIZE the size of the symbol lookup cache can be
-# set using LOOKUP_CACHE_SIZE. This cache is used to resolve symbols given
-# their name and scope. Since this can be an expensive process and often the
-# same symbol appear multiple times in the code, doxygen keeps a cache of
-# pre-resolved symbols. If the cache is too small doxygen will become slower.
-# If the cache is too large, memory is wasted. The cache size is given by this
-# formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range is 0..9, the default is 0,
-# corresponding to a cache size of 2^16 = 65536 symbols.
+# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This
+# cache is used to resolve symbols given their name and scope. Since this can be
+# an expensive process and often the same symbol appears multiple times in the
+# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small
+# doxygen will become slower. If the cache is too large, memory is wasted. The
+# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range
+# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536
+# symbols. At the end of a run doxygen will report the cache usage and suggest
+# the optimal cache size from a speed point of view.
+# Minimum value: 0, maximum value: 9, default value: 0.
LOOKUP_CACHE_SIZE = 0
+# The NUM_PROC_THREADS specifies the number of threads doxygen is allowed to use
+# during processing. When set to 0 doxygen will based this on the number of
+# cores available in the system. You can set it explicitly to a value larger
+# than 0 to get more control over the balance between CPU load and processing
+# speed. At this moment only the input processing can be done using multiple
+# threads. Since this is still an experimental feature the default is set to 1,
+# which effectively disables parallel processing. Please report any issues you
+# encounter. Generating dot graphs in parallel is controlled by the
+# DOT_NUM_THREADS setting.
+# Minimum value: 0, maximum value: 32, default value: 1.
+
+NUM_PROC_THREADS = 1
+
+# If the TIMESTAMP tag is set different from NO then each generated page will
+# contain the date or date and time when the page was generated. Setting this to
+# NO can help when comparing the output of multiple runs.
+# Possible values are: YES, NO, DATETIME and DATE.
+# The default value is: NO.
+
+TIMESTAMP = NO
+
#---------------------------------------------------------------------------
# Build related configuration options
#---------------------------------------------------------------------------
-# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
-# documentation are documented, even if no documentation was available.
-# Private class members and static file members will be hidden unless
-# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
+# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in
+# documentation are documented, even if no documentation was available. Private
+# class members and static file members will be hidden unless the
+# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES.
+# Note: This will also disable the warnings about undocumented members that are
+# normally produced when WARNINGS is set to YES.
+# The default value is: NO.
EXTRACT_ALL = NO
-# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
-# will be included in the documentation.
+# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
+# be included in the documentation.
+# The default value is: NO.
EXTRACT_PRIVATE = NO
-# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal
+# If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual
+# methods of a class will be included in the documentation.
+# The default value is: NO.
+
+EXTRACT_PRIV_VIRTUAL = NO
+
+# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal
# scope will be included in the documentation.
+# The default value is: NO.
EXTRACT_PACKAGE = NO
-# If the EXTRACT_STATIC tag is set to YES all static members of a file
-# will be included in the documentation.
+# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be
+# included in the documentation.
+# The default value is: NO.
EXTRACT_STATIC = NO
-# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
-# defined locally in source files will be included in the documentation.
-# If set to NO only classes defined in header files are included.
+# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
+# locally in source files will be included in the documentation. If set to NO,
+# only classes defined in header files are included. Does not have any effect
+# for Java sources.
+# The default value is: YES.
EXTRACT_LOCAL_CLASSES = YES
-# This flag is only useful for Objective-C code. When set to YES local
-# methods, which are defined in the implementation section but not in
-# the interface are included in the documentation.
-# If set to NO (the default) only methods in the interface are included.
+# This flag is only useful for Objective-C code. If set to YES, local methods,
+# which are defined in the implementation section but not in the interface are
+# included in the documentation. If set to NO, only methods in the interface are
+# included.
+# The default value is: NO.
EXTRACT_LOCAL_METHODS = NO
# If this flag is set to YES, the members of anonymous namespaces will be
# extracted and appear in the documentation as a namespace called
-# 'anonymous_namespace{file}', where file will be replaced with the base
-# name of the file that contains the anonymous namespace. By default
-# anonymous namespaces are hidden.
+# 'anonymous_namespace{file}', where file will be replaced with the base name of
+# the file that contains the anonymous namespace. By default anonymous namespace
+# are hidden.
+# The default value is: NO.
EXTRACT_ANON_NSPACES = NO
-# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all
-# undocumented members of documented classes, files or namespaces.
-# If set to NO (the default) these members will be included in the
-# various overviews, but no documentation section is generated.
-# This option has no effect if EXTRACT_ALL is enabled.
+# If this flag is set to YES, the name of an unnamed parameter in a declaration
+# will be determined by the corresponding definition. By default unnamed
+# parameters remain unnamed in the output.
+# The default value is: YES.
+
+RESOLVE_UNNAMED_PARAMS = YES
+
+# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all
+# undocumented members inside documented classes or files. If set to NO these
+# members will be included in the various overviews, but no documentation
+# section is generated. This option has no effect if EXTRACT_ALL is enabled.
+# The default value is: NO.
HIDE_UNDOC_MEMBERS = NO
-# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
-# undocumented classes that are normally visible in the class hierarchy.
-# If set to NO (the default) these classes will be included in the various
-# overviews. This option has no effect if EXTRACT_ALL is enabled.
+# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all
+# undocumented classes that are normally visible in the class hierarchy. If set
+# to NO, these classes will be included in the various overviews. This option
+# will also hide undocumented C++ concepts if enabled. This option has no effect
+# if EXTRACT_ALL is enabled.
+# The default value is: NO.
HIDE_UNDOC_CLASSES = NO
-# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all
-# friend (class|struct|union) declarations.
-# If set to NO (the default) these declarations will be included in the
+# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend
+# declarations. If set to NO, these declarations will be included in the
# documentation.
+# The default value is: NO.
HIDE_FRIEND_COMPOUNDS = NO
-# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any
-# documentation blocks found inside the body of a function.
-# If set to NO (the default) these blocks will be appended to the
-# function's detailed documentation block.
+# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any
+# documentation blocks found inside the body of a function. If set to NO, these
+# blocks will be appended to the function's detailed documentation block.
+# The default value is: NO.
HIDE_IN_BODY_DOCS = NO
-# The INTERNAL_DOCS tag determines if documentation
-# that is typed after a \internal command is included. If the tag is set
-# to NO (the default) then the documentation will be excluded.
-# Set it to YES to include the internal documentation.
+# The INTERNAL_DOCS tag determines if documentation that is typed after a
+# \internal command is included. If the tag is set to NO then the documentation
+# will be excluded. Set it to YES to include the internal documentation.
+# The default value is: NO.
INTERNAL_DOCS = NO
-# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
-# file names in lower-case letters. If set to YES upper-case letters are also
-# allowed. This is useful if you have classes or files whose names only differ
-# in case and if your file system supports case sensitive file names. Windows
-# and Mac users are advised to set this option to NO.
+# With the correct setting of option CASE_SENSE_NAMES doxygen will better be
+# able to match the capabilities of the underlying filesystem. In case the
+# filesystem is case sensitive (i.e. it supports files in the same directory
+# whose names only differ in casing), the option must be set to YES to properly
+# deal with such files in case they appear in the input. For filesystems that
+# are not case sensitive the option should be set to NO to properly deal with
+# output files written for symbols that only differ in casing, such as for two
+# classes, one named CLASS and the other named Class, and to also support
+# references to files without having to specify the exact matching casing. On
+# Windows (including Cygwin) and MacOS, users should typically set this option
+# to NO, whereas on Linux or other Unix flavors it should typically be set to
+# YES.
+# Possible values are: SYSTEM, NO and YES.
+# The default value is: SYSTEM.
CASE_SENSE_NAMES = YES
-# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen
-# will show members with their full class and namespace scopes in the
-# documentation. If set to YES the scope will be hidden.
+# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with
+# their full class and namespace scopes in the documentation. If set to YES, the
+# scope will be hidden.
+# The default value is: NO.
HIDE_SCOPE_NAMES = NO
-# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
-# will put a list of the files that are included by a file in the documentation
-# of that file.
+# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will
+# append additional text to a page's title, such as Class Reference. If set to
+# YES the compound reference will be hidden.
+# The default value is: NO.
+
+HIDE_COMPOUND_REFERENCE= NO
+
+# If the SHOW_HEADERFILE tag is set to YES then the documentation for a class
+# will show which file needs to be included to use the class.
+# The default value is: YES.
+
+SHOW_HEADERFILE = YES
+
+# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of
+# the files that are included by a file in the documentation of that file.
+# The default value is: YES.
SHOW_INCLUDE_FILES = YES
-# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen
-# will list include files with double quotes in the documentation
-# rather than with sharp brackets.
+# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
+# grouped member an include statement to the documentation, telling the reader
+# which file to include in order to use the member.
+# The default value is: NO.
+
+SHOW_GROUPED_MEMB_INC = NO
+
+# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include
+# files with double quotes in the documentation rather than with sharp brackets.
+# The default value is: NO.
FORCE_LOCAL_INCLUDES = NO
-# If the INLINE_INFO tag is set to YES (the default) then a tag [inline]
-# is inserted in the documentation for inline members.
+# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the
+# documentation for inline members.
+# The default value is: YES.
INLINE_INFO = YES
-# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen
-# will sort the (detailed) documentation of file and class members
-# alphabetically by member name. If set to NO the members will appear in
-# declaration order.
+# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the
+# (detailed) documentation of file and class members alphabetically by member
+# name. If set to NO, the members will appear in declaration order.
+# The default value is: YES.
SORT_MEMBER_DOCS = YES
-# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the
-# brief documentation of file, namespace and class members alphabetically
-# by member name. If set to NO (the default) the members will appear in
-# declaration order.
+# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
+# descriptions of file, namespace and class members alphabetically by member
+# name. If set to NO, the members will appear in declaration order. Note that
+# this will also influence the order of the classes in the class list.
+# The default value is: NO.
SORT_BRIEF_DOCS = NO
-# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen
-# will sort the (brief and detailed) documentation of class members so that
-# constructors and destructors are listed first. If set to NO (the default)
-# the constructors will appear in the respective orders defined by
-# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS.
-# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO
-# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO.
+# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
+# (brief and detailed) documentation of class members so that constructors and
+# destructors are listed first. If set to NO the constructors will appear in the
+# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS.
+# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief
+# member documentation.
+# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting
+# detailed member documentation.
+# The default value is: NO.
SORT_MEMBERS_CTORS_1ST = NO
-# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the
-# hierarchy of group names into alphabetical order. If set to NO (the default)
-# the group names will appear in their defined order.
+# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy
+# of group names into alphabetical order. If set to NO the group names will
+# appear in their defined order.
+# The default value is: NO.
SORT_GROUP_NAMES = NO
-# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be
-# sorted by fully-qualified names, including namespaces. If set to
-# NO (the default), the class list will be sorted only by class name,
-# not including the namespace part.
+# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
+# fully-qualified names, including namespaces. If set to NO, the class list will
+# be sorted only by class name, not including the namespace part.
# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
-# Note: This option applies only to the class list, not to the
-# alphabetical list.
+# Note: This option applies only to the class list, not to the alphabetical
+# list.
+# The default value is: NO.
SORT_BY_SCOPE_NAME = NO
-# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to
-# do proper type resolution of all parameters of a function it will reject a
-# match between the prototype and the implementation of a member function even
-# if there is only one candidate or it is obvious which candidate to choose
-# by doing a simple string match. By disabling STRICT_PROTO_MATCHING doxygen
-# will still accept a match between prototype and implementation in such cases.
+# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper
+# type resolution of all parameters of a function it will reject a match between
+# the prototype and the implementation of a member function even if there is
+# only one candidate or it is obvious which candidate to choose by doing a
+# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still
+# accept a match between prototype and implementation in such cases.
+# The default value is: NO.
STRICT_PROTO_MATCHING = NO
-# The GENERATE_TODOLIST tag can be used to enable (YES) or
-# disable (NO) the todo list. This list is created by putting \todo
-# commands in the documentation.
+# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo
+# list. This list is created by putting \todo commands in the documentation.
+# The default value is: YES.
GENERATE_TODOLIST = YES
-# The GENERATE_TESTLIST tag can be used to enable (YES) or
-# disable (NO) the test list. This list is created by putting \test
-# commands in the documentation.
+# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test
+# list. This list is created by putting \test commands in the documentation.
+# The default value is: YES.
GENERATE_TESTLIST = NO
-# The GENERATE_BUGLIST tag can be used to enable (YES) or
-# disable (NO) the bug list. This list is created by putting \bug
-# commands in the documentation.
+# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug
+# list. This list is created by putting \bug commands in the documentation.
+# The default value is: YES.
GENERATE_BUGLIST = NO
-# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or
-# disable (NO) the deprecated list. This list is created by putting
-# \deprecated commands in the documentation.
+# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO)
+# the deprecated list. This list is created by putting \deprecated commands in
+# the documentation.
+# The default value is: YES.
GENERATE_DEPRECATEDLIST= YES
-# The ENABLED_SECTIONS tag can be used to enable conditional
-# documentation sections, marked by \if section-label ... \endif
-# and \cond section-label ... \endcond blocks.
+# The ENABLED_SECTIONS tag can be used to enable conditional documentation
+# sections, marked by \if <section_label> ... \endif and \cond <section_label>
+# ... \endcond blocks.
ENABLED_SECTIONS =
-# The MAX_INITIALIZER_LINES tag determines the maximum number of lines
-# the initial value of a variable or macro consists of for it to appear in
-# the documentation. If the initializer consists of more lines than specified
-# here it will be hidden. Use a value of 0 to hide initializers completely.
-# The appearance of the initializer of individual variables and macros in the
-# documentation can be controlled using \showinitializer or \hideinitializer
-# command in the documentation regardless of this setting.
+# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the
+# initial value of a variable or macro / define can have for it to appear in the
+# documentation. If the initializer consists of more lines than specified here
+# it will be hidden. Use a value of 0 to hide initializers completely. The
+# appearance of the value of individual variables and macros / defines can be
+# controlled using \showinitializer or \hideinitializer command in the
+# documentation regardless of this setting.
+# Minimum value: 0, maximum value: 10000, default value: 30.
MAX_INITIALIZER_LINES = 30
-# Set the SHOW_USED_FILES tag to NO to disable the list of files generated
-# at the bottom of the documentation of classes and structs. If set to YES the
+# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at
+# the bottom of the documentation of classes and structs. If set to YES, the
# list will mention the files that were used to generate the documentation.
+# The default value is: YES.
SHOW_USED_FILES = YES
-# Set the SHOW_FILES tag to NO to disable the generation of the Files page.
-# This will remove the Files entry from the Quick Index and from the
-# Folder Tree View (if specified). The default is YES.
+# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This
+# will remove the Files entry from the Quick Index and from the Folder Tree View
+# (if specified).
+# The default value is: YES.
SHOW_FILES = YES
-# Set the SHOW_NAMESPACES tag to NO to disable the generation of the
-# Namespaces page.
-# This will remove the Namespaces entry from the Quick Index
-# and from the Folder Tree View (if specified). The default is YES.
+# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces
+# page. This will remove the Namespaces entry from the Quick Index and from the
+# Folder Tree View (if specified).
+# The default value is: YES.
SHOW_NAMESPACES = YES
# The FILE_VERSION_FILTER tag can be used to specify a program or script that
# doxygen should invoke to get the current version for each file (typically from
# the version control system). Doxygen will invoke the program by executing (via
-# popen()) the command <command> <input-file>, where <command> is the value of
-# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file
-# provided by doxygen. Whatever the program writes to standard output
-# is used as the file version. See the manual for examples.
+# popen()) the command command input-file, where command is the value of the
+# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided
+# by doxygen. Whatever the program writes to standard output is used as the file
+# version. For an example see the documentation.
FILE_VERSION_FILTER =
# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed
# by doxygen. The layout file controls the global structure of the generated
# output files in an output format independent way. To create the layout file
-# that represents doxygen's defaults, run doxygen with the -l option.
-# You can optionally specify a file name after the option, if omitted
-# DoxygenLayout.xml will be used as the name of the layout file.
+# that represents doxygen's defaults, run doxygen with the -l option. You can
+# optionally specify a file name after the option, if omitted DoxygenLayout.xml
+# will be used as the name of the layout file. See also section "Changing the
+# layout of pages" for information.
+#
+# Note that if you run doxygen from a directory containing a file called
+# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
+# tag is left empty.
LAYOUT_FILE =
-# The CITE_BIB_FILES tag can be used to specify one or more bib files
-# containing the references data. This must be a list of .bib files. The
-# .bib extension is automatically appended if omitted. Using this command
-# requires the bibtex tool to be installed. See also
-# http://en.wikipedia.org/wiki/BibTeX for more info. For LaTeX the style
-# of the bibliography can be controlled using LATEX_BIB_STYLE. To use this
-# feature you need bibtex and perl available in the search path. Do not use
-# file names with spaces, bibtex cannot handle them.
+# The CITE_BIB_FILES tag can be used to specify one or more bib files containing
+# the reference definitions. This must be a list of .bib files. The .bib
+# extension is automatically appended if omitted. This requires the bibtex tool
+# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info.
+# For LaTeX the style of the bibliography can be controlled using
+# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the
+# search path. See also \cite for info how to create references.
CITE_BIB_FILES =
#---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
+# Configuration options related to warning and progress messages
#---------------------------------------------------------------------------
-# The QUIET tag can be used to turn on/off the messages that are generated
-# by doxygen. Possible values are YES and NO. If left blank NO is used.
+# The QUIET tag can be used to turn on/off the messages that are generated to
+# standard output by doxygen. If QUIET is set to YES this implies that the
+# messages are off.
+# The default value is: NO.
QUIET = YES
# The WARNINGS tag can be used to turn on/off the warning messages that are
-# generated by doxygen. Possible values are YES and NO. If left blank
-# NO is used.
+# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES
+# this implies that the warnings are on.
+#
+# Tip: Turn warnings on while writing the documentation.
+# The default value is: YES.
WARNINGS = YES
-# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings
-# for undocumented members. If EXTRACT_ALL is set to YES then this flag will
-# automatically be disabled.
+# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate
+# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag
+# will automatically be disabled.
+# The default value is: YES.
WARN_IF_UNDOCUMENTED = YES
-# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
-# potential errors in the documentation, such as not documenting some
-# parameters in a documented function, or documenting parameters that
-# don't exist or using markup commands wrongly.
+# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
+# potential errors in the documentation, such as documenting some parameters in
+# a documented function twice, or documenting parameters that don't exist or
+# using markup commands wrongly.
+# The default value is: YES.
WARN_IF_DOC_ERROR = YES
-# The WARN_NO_PARAMDOC option can be enabled to get warnings for
-# functions that are documented, but have no documentation for their parameters
-# or return value. If set to NO (the default) doxygen will only warn about
-# wrong or incomplete parameter documentation, but not about the absence of
-# documentation.
+# If WARN_IF_INCOMPLETE_DOC is set to YES, doxygen will warn about incomplete
+# function parameter documentation. If set to NO, doxygen will accept that some
+# parameters have no documentation without warning.
+# The default value is: YES.
+
+WARN_IF_INCOMPLETE_DOC = YES
+
+# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that
+# are documented, but have no documentation for their parameters or return
+# value. If set to NO, doxygen will only warn about wrong parameter
+# documentation, but not about the absence of documentation. If EXTRACT_ALL is
+# set to YES then this flag will automatically be disabled. See also
+# WARN_IF_INCOMPLETE_DOC
+# The default value is: NO.
WARN_NO_PARAMDOC = NO
-# The WARN_FORMAT tag determines the format of the warning messages that
-# doxygen can produce. The string should contain the $file, $line, and $text
-# tags, which will be replaced by the file and line number from which the
-# warning originated and the warning text. Optionally the format may contain
-# $version, which will be replaced by the version of the file (if it could
-# be obtained via FILE_VERSION_FILTER)
+# If WARN_IF_UNDOC_ENUM_VAL option is set to YES, doxygen will warn about
+# undocumented enumeration values. If set to NO, doxygen will accept
+# undocumented enumeration values. If EXTRACT_ALL is set to YES then this flag
+# will automatically be disabled.
+# The default value is: NO.
+
+WARN_IF_UNDOC_ENUM_VAL = NO
+
+# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when
+# a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS
+# then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but
+# at the end of the doxygen process doxygen will return with a non-zero status.
+# If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS_PRINT then doxygen behaves
+# like FAIL_ON_WARNINGS but in case no WARN_LOGFILE is defined doxygen will not
+# write the warning messages in between other messages but write them at the end
+# of a run, in case a WARN_LOGFILE is defined the warning messages will be
+# besides being in the defined file also be shown at the end of a run, unless
+# the WARN_LOGFILE is defined as - i.e. standard output (stdout) in that case
+# the behavior will remain as with the setting FAIL_ON_WARNINGS.
+# Possible values are: NO, YES, FAIL_ON_WARNINGS and FAIL_ON_WARNINGS_PRINT.
+# The default value is: NO.
+
+WARN_AS_ERROR = NO
+
+# The WARN_FORMAT tag determines the format of the warning messages that doxygen
+# can produce. The string should contain the $file, $line, and $text tags, which
+# will be replaced by the file and line number from which the warning originated
+# and the warning text. Optionally the format may contain $version, which will
+# be replaced by the version of the file (if it could be obtained via
+# FILE_VERSION_FILTER)
+# See also: WARN_LINE_FORMAT
+# The default value is: $file:$line: $text.
WARN_FORMAT =
-# The WARN_LOGFILE tag can be used to specify a file to which warning
-# and error messages should be written. If left blank the output is written
-# to stderr.
+# In the $text part of the WARN_FORMAT command it is possible that a reference
+# to a more specific place is given. To make it easier to jump to this place
+# (outside of doxygen) the user can define a custom "cut" / "paste" string.
+# Example:
+# WARN_LINE_FORMAT = "'vi $file +$line'"
+# See also: WARN_FORMAT
+# The default value is: at line $line of file $file.
+
+WARN_LINE_FORMAT = "at line $line of file $file"
+
+# The WARN_LOGFILE tag can be used to specify a file to which warning and error
+# messages should be written. If left blank the output is written to standard
+# error (stderr). In case the file specified cannot be opened for writing the
+# warning and error messages are written to standard error. When as file - is
+# specified the warning and error messages are written to standard output
+# (stdout).
WARN_LOGFILE = doxygen.log
#---------------------------------------------------------------------------
-# configuration options related to the input files
+# Configuration options related to the input files
#---------------------------------------------------------------------------
-# The INPUT tag can be used to specify the files and/or directories that contain
-# documented source files. You may enter file names like "myfile.cpp" or
-# directories like "/usr/src/myproject". Separate the files or directories
-# with spaces.
+# The INPUT tag is used to specify the files and/or directories that contain
+# documented source files. You may enter file names like myfile.cpp or
+# directories like /usr/src/myproject. Separate the files or directories with
+# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
+# Note: If this tag is empty the current directory is searched.
INPUT = ${CMAKE_SOURCE_DIR}/libgnucash \
${CMAKE_SOURCE_DIR}/gnucash \
@@ -659,20 +940,42 @@ INPUT = ${CMAKE_SOURCE_DIR}/libgnucash \
${CMAKE_SOURCE_DIR}/libgnucash/engine/
# This tag can be used to specify the character encoding of the source files
-# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
-# also the default input encoding. Doxygen uses libiconv (or the iconv built
-# into libc) for the transcoding. See https://www.gnu.org/software/libiconv for
-# the list of possible encodings.
+# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
+# libiconv (or the iconv built into libc) for the transcoding. See the libiconv
+# documentation (see:
+# https://www.gnu.org/software/libiconv/) for the list of possible encodings.
+# See also: INPUT_FILE_ENCODING
+# The default value is: UTF-8.
INPUT_ENCODING = UTF-8
+# This tag can be used to specify the character encoding of the source files
+# that doxygen parses The INPUT_FILE_ENCODING tag can be used to specify
+# character encoding on a per file pattern basis. Doxygen will compare the file
+# name with each pattern and apply the encoding instead of the default
+# INPUT_ENCODING) if there is a match. The character encodings are a list of the
+# form: pattern=encoding (like *.php=ISO-8859-1). See cfg_input_encoding
+# "INPUT_ENCODING" for further information on supported encodings.
+
+INPUT_FILE_ENCODING =
+
# If the value of the INPUT tag contains directories, you can use the
-# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
-# and *.h) to filter out the source-files in the directories. If left
-# blank the following patterns are tested:
-# *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh
-# *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py
-# *.f90 *.f *.for *.vhd *.vhdl
+# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and
+# *.h) to filter out the source-files in the directories.
+#
+# Note that for custom extensions or not directly supported extensions you also
+# need to set EXTENSION_MAPPING for the extension otherwise the files are not
+# read by doxygen.
+#
+# Note the list of default checked file patterns might differ from the list of
+# default file extension mappings.
+#
+# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp,
+# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h,
+# *.hh, *.hxx, *.hpp, *.h++, *.l, *.cs, *.d, *.php, *.php4, *.php5, *.phtml,
+# *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C
+# comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd,
+# *.vhdl, *.ucf, *.qsf and *.ice.
FILE_PATTERNS = *.c \
*.h \
@@ -682,15 +985,16 @@ FILE_PATTERNS = *.c \
*.cpp \
*.hpp
-# The RECURSIVE tag can be used to turn specify whether or not subdirectories
-# should be searched for input files as well. Possible values are YES and NO.
-# If left blank NO is used.
+# The RECURSIVE tag can be used to specify whether or not subdirectories should
+# be searched for input files as well.
+# The default value is: NO.
RECURSIVE = YES
# The EXCLUDE tag can be used to specify files and/or directories that should be
# excluded from the INPUT source files. This way you can easily exclude a
# subdirectory from a directory tree whose root is specified with the INPUT tag.
+#
# Note that relative paths are relative to the directory from which doxygen is
# run.
@@ -699,14 +1003,16 @@ EXCLUDE =
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded
# from the input.
+# The default value is: NO.
EXCLUDE_SYMLINKS = YES
# If the value of the INPUT tag contains directories, you can use the
# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
-# certain files from those directories. Note that the wildcards are matched
-# against the file with absolute path, so to exclude all test directories
-# for example use the pattern */test/*
+# certain files from those directories.
+#
+# Note that the wildcards are matched against the file with absolute path, so to
+# exclude all test directories for example use the pattern */test/*
EXCLUDE_PATTERNS = */test/*
@@ -714,808 +1020,1273 @@ EXCLUDE_PATTERNS = */test/*
# (namespaces, classes, functions, etc.) that should be excluded from the
# output. The symbol name can be a fully qualified name, a word, or if the
# wildcard * is used, a substring. Examples: ANamespace, AClass,
-# AClass::ANamespace, ANamespace::*Test
+# ANamespace::AClass, ANamespace::*Test
EXCLUDE_SYMBOLS =
-# The EXAMPLE_PATH tag can be used to specify one or more files or
-# directories that contain example code fragments that are included (see
-# the \include command).
+# The EXAMPLE_PATH tag can be used to specify one or more files or directories
+# that contain example code fragments that are included (see the \include
+# command).
EXAMPLE_PATH =
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
-# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
-# and *.h) to filter out the source-files in the directories. If left
-# blank all files are included.
+# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
+# *.h) to filter out the source-files in the directories. If left blank all
+# files are included.
EXAMPLE_PATTERNS =
# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
-# searched for input files to be used with the \include or \dontinclude
-# commands irrespective of the value of the RECURSIVE tag.
-# Possible values are YES and NO. If left blank NO is used.
+# searched for input files to be used with the \include or \dontinclude commands
+# irrespective of the value of the RECURSIVE tag.
+# The default value is: NO.
EXAMPLE_RECURSIVE = NO
-# The IMAGE_PATH tag can be used to specify one or more files or
-# directories that contain image that are included in the documentation (see
-# the \image command).
+# The IMAGE_PATH tag can be used to specify one or more files or directories
+# that contain images that are to be included in the documentation (see the
+# \image command).
IMAGE_PATH =
# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
-# by executing (via popen()) the command <filter> <input-file>, where <filter>
-# is the value of the INPUT_FILTER tag, and <input-file> is the name of an
-# input file. Doxygen will then use the output that the filter program writes
-# to standard output.
-# If FILTER_PATTERNS is specified, this tag will be
-# ignored.
+# by executing (via popen()) the command:
+#
+# <filter> <input-file>
+#
+# where <filter> is the value of the INPUT_FILTER tag, and <input-file> is the
+# name of an input file. Doxygen will then use the output that the filter
+# program writes to standard output. If FILTER_PATTERNS is specified, this tag
+# will be ignored.
+#
+# Note that the filter must not add or remove lines; it is applied before the
+# code is scanned, but not when the output code is generated. If lines are added
+# or removed, the anchors will not be placed correctly.
+#
+# Note that doxygen will use the data processed and written to standard output
+# for further processing, therefore nothing else, like debug statements or used
+# commands (so in case of a Windows batch file always use @echo OFF), should be
+# written to standard output.
+#
+# Note that for custom extensions or not directly supported extensions you also
+# need to set EXTENSION_MAPPING for the extension otherwise the files are not
+# properly processed by doxygen.
INPUT_FILTER =
# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
-# basis.
-# Doxygen will compare the file name with each pattern and apply the
-# filter if there is a match.
-# The filters are a list of the form:
-# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further
-# info on how filters are used. If FILTER_PATTERNS is empty or if
-# non of the patterns match the file name, INPUT_FILTER is applied.
+# basis. Doxygen will compare the file name with each pattern and apply the
+# filter if there is a match. The filters are a list of the form: pattern=filter
+# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how
+# filters are used. If the FILTER_PATTERNS tag is empty or if none of the
+# patterns match the file name, INPUT_FILTER is applied.
+#
+# Note that for custom extensions or not directly supported extensions you also
+# need to set EXTENSION_MAPPING for the extension otherwise the files are not
+# properly processed by doxygen.
FILTER_PATTERNS =
# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
-# INPUT_FILTER) will be used to filter the input files when producing source
-# files to browse (i.e. when SOURCE_BROWSER is set to YES).
+# INPUT_FILTER) will also be used to filter the input files that are used for
+# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES).
+# The default value is: NO.
FILTER_SOURCE_FILES = NO
# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file
-# pattern. A pattern will override the setting for FILTER_PATTERN (if any)
-# and it is also possible to disable source filtering for a specific pattern
-# using *.ext= (so without naming a filter). This option only has effect when
-# FILTER_SOURCE_FILES is enabled.
+# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and
+# it is also possible to disable source filtering for a specific pattern using
+# *.ext= (so without naming a filter).
+# This tag requires that the tag FILTER_SOURCE_FILES is set to YES.
FILTER_SOURCE_PATTERNS =
-# If the USE_MD_FILE_AS_MAINPAGE tag refers to the name of a markdown file that
-# is part of the input, its contents will be placed on the main page (index.html).
-# This can be useful if you have a project on for instance GitHub and want reuse
-# the introduction page also for the doxygen output.
+# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that
+# is part of the input, its contents will be placed on the main page
+# (index.html). This can be useful if you have a project on for instance GitHub
+# and want to reuse the introduction page also for the doxygen output.
USE_MDFILE_AS_MAINPAGE =
+# The Fortran standard specifies that for fixed formatted Fortran code all
+# characters from position 72 are to be considered as comment. A common
+# extension is to allow longer lines before the automatic comment starts. The
+# setting FORTRAN_COMMENT_AFTER will also make it possible that longer lines can
+# be processed before the automatic comment starts.
+# Minimum value: 7, maximum value: 10000, default value: 72.
+
+FORTRAN_COMMENT_AFTER = 72
+
#---------------------------------------------------------------------------
-# configuration options related to source browsing
+# Configuration options related to source browsing
#---------------------------------------------------------------------------
-# If the SOURCE_BROWSER tag is set to YES then a list of source files will
-# be generated. Documented entities will be cross-referenced with these sources.
-# Note: To get rid of all source code in the generated output, make sure also
-# VERBATIM_HEADERS is set to NO.
+# If the SOURCE_BROWSER tag is set to YES then a list of source files will be
+# generated. Documented entities will be cross-referenced with these sources.
+#
+# Note: To get rid of all source code in the generated output, make sure that
+# also VERBATIM_HEADERS is set to NO.
+# The default value is: NO.
SOURCE_BROWSER = YES
-# Setting the INLINE_SOURCES tag to YES will include the body
-# of functions and classes directly in the documentation.
+# Setting the INLINE_SOURCES tag to YES will include the body of functions,
+# classes and enums directly into the documentation.
+# The default value is: NO.
INLINE_SOURCES = YES
-# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
-# doxygen to hide any special comment blocks from generated source code
-# fragments. Normal C, C++ and Fortran comments will always remain visible.
+# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any
+# special comment blocks from generated source code fragments. Normal C, C++ and
+# Fortran comments will always remain visible.
+# The default value is: YES.
STRIP_CODE_COMMENTS = YES
-# If the REFERENCED_BY_RELATION tag is set to YES
-# then for each documented function all documented
-# functions referencing it will be listed.
+# If the REFERENCED_BY_RELATION tag is set to YES then for each documented
+# entity all documented functions referencing it will be listed.
+# The default value is: NO.
REFERENCED_BY_RELATION = NO
-# If the REFERENCES_RELATION tag is set to YES
-# then for each documented function all documented entities
-# called/used by that function will be listed.
+# If the REFERENCES_RELATION tag is set to YES then for each documented function
+# all documented entities called/used by that function will be listed.
+# The default value is: NO.
REFERENCES_RELATION = NO
-# If the REFERENCES_LINK_SOURCE tag is set to YES (the default)
-# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from
-# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will
-# link to the source code.
-# Otherwise they will link to the documentation.
+# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set
+# to YES then the hyperlinks from functions in REFERENCES_RELATION and
+# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will
+# link to the documentation.
+# The default value is: YES.
REFERENCES_LINK_SOURCE = YES
-# If the USE_HTAGS tag is set to YES then the references to source code
-# will point to the HTML generated by the htags(1) tool instead of doxygen
-# built-in source browser. The htags tool is part of GNU's global source
-# tagging system (see https://www.gnu.org/software/global/global.html). You
-# will need version 4.8.6 or higher.
+# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the
+# source code will show a tooltip with additional information such as prototype,
+# brief description and links to the definition and documentation. Since this
+# will make the HTML file larger and loading of large files a bit slower, you
+# can opt to disable this feature.
+# The default value is: YES.
+# This tag requires that the tag SOURCE_BROWSER is set to YES.
+
+SOURCE_TOOLTIPS = YES
+
+# If the USE_HTAGS tag is set to YES then the references to source code will
+# point to the HTML generated by the htags(1) tool instead of doxygen built-in
+# source browser. The htags tool is part of GNU's global source tagging system
+# (see https://www.gnu.org/software/global/global.html). You will need version
+# 4.8.6 or higher.
+#
+# To use it do the following:
+# - Install the latest version of global
+# - Enable SOURCE_BROWSER and USE_HTAGS in the configuration file
+# - Make sure the INPUT points to the root of the source tree
+# - Run doxygen as normal
+#
+# Doxygen will invoke htags (and that will in turn invoke gtags), so these
+# tools must be available from the command line (i.e. in the search path).
+#
+# The result: instead of the source browser generated by doxygen, the links to
+# source code will now point to the output of htags.
+# The default value is: NO.
+# This tag requires that the tag SOURCE_BROWSER is set to YES.
USE_HTAGS = NO
-# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen
-# will generate a verbatim copy of the header file for each class for
-# which an include is specified. Set to NO to disable this.
+# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a
+# verbatim copy of the header file for each class for which an include is
+# specified. Set to NO to disable this.
+# See also: Section \class.
+# The default value is: YES.
VERBATIM_HEADERS = NO
+# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the
+# clang parser (see:
+# http://clang.llvm.org/) for more accurate parsing at the cost of reduced
+# performance. This can be particularly helpful with template rich C++ code for
+# which doxygen's built-in parser lacks the necessary type information.
+# Note: The availability of this option depends on whether or not doxygen was
+# generated with the -Duse_libclang=ON option for CMake.
+# The default value is: NO.
+
+CLANG_ASSISTED_PARSING = NO
+
+# If the CLANG_ASSISTED_PARSING tag is set to YES and the CLANG_ADD_INC_PATHS
+# tag is set to YES then doxygen will add the directory of each input to the
+# include path.
+# The default value is: YES.
+# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES.
+
+CLANG_ADD_INC_PATHS = YES
+
+# If clang assisted parsing is enabled you can provide the compiler with command
+# line options that you would normally use when invoking the compiler. Note that
+# the include paths will already be set by doxygen for the files and directories
+# specified with INPUT and INCLUDE_PATH.
+# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES.
+
+CLANG_OPTIONS =
+
+# If clang assisted parsing is enabled you can provide the clang parser with the
+# path to the directory containing a file called compile_commands.json. This
+# file is the compilation database (see:
+# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the
+# options used when the source files were built. This is equivalent to
+# specifying the -p option to a clang tool, such as clang-check. These options
+# will then be passed to the parser. Any options specified with CLANG_OPTIONS
+# will be added as well.
+# Note: The availability of this option depends on whether or not doxygen was
+# generated with the -Duse_libclang=ON option for CMake.
+
+CLANG_DATABASE_PATH =
+
#---------------------------------------------------------------------------
-# configuration options related to the alphabetical class index
+# Configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
-# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index
-# of all compounds will be generated. Enable this if the project
-# contains a lot of classes, structs, unions or interfaces.
+# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all
+# compounds will be generated. Enable this if the project contains a lot of
+# classes, structs, unions or interfaces.
+# The default value is: YES.
ALPHABETICAL_INDEX = YES
-# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
-# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
-# in which this list will be split (can be a number in the range [1..20])
-
-COLS_IN_ALPHA_INDEX = 5
-
-# In case all classes in a project start with a common prefix, all
-# classes will be put under the same header in the alphabetical index.
-# The IGNORE_PREFIX tag can be used to specify one or more prefixes that
-# should be ignored while generating the index headers.
+# The IGNORE_PREFIX tag can be used to specify a prefix (or a list of prefixes)
+# that should be ignored while generating the index headers. The IGNORE_PREFIX
+# tag works for classes, function and member names. The entity will be placed in
+# the alphabetical list under the first letter of the entity name that remains
+# after removing the prefix.
+# This tag requires that the tag ALPHABETICAL_INDEX is set to YES.
IGNORE_PREFIX =
#---------------------------------------------------------------------------
-# configuration options related to the HTML output
+# Configuration options related to the HTML output
#---------------------------------------------------------------------------
-# If the GENERATE_HTML tag is set to YES (the default) Doxygen will
-# generate HTML output.
+# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
+# The default value is: YES.
GENERATE_HTML = YES
-# The HTML_OUTPUT tag is used to specify where the HTML docs will be put.
-# If a relative path is entered the value of OUTPUT_DIRECTORY will be
-# put in front of it. If left blank `html' will be used as the default path.
+# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a
+# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
+# it.
+# The default directory is: html.
+# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_OUTPUT =
-# The HTML_FILE_EXTENSION tag can be used to specify the file extension for
-# each generated HTML page (for example: .htm,.php,.asp). If it is left blank
-# doxygen will generate files with .html extension.
+# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
+# generated HTML page (for example: .htm, .php, .asp).
+# The default value is: .html.
+# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_FILE_EXTENSION =
-# The HTML_HEADER tag can be used to specify a personal HTML header for
-# each generated HTML page. If it is left blank doxygen will generate a
-# standard header. Note that when using a custom header you are responsible
-# for the proper inclusion of any scripts and style sheets that doxygen
-# needs, which is dependent on the configuration options used.
-# It is advised to generate a default header using "doxygen -w html
-# header.html footer.html stylesheet.css YourConfigFile" and then modify
-# that header. Note that the header is subject to change so you typically
-# have to redo this when upgrading to a newer version of doxygen or when
-# changing the value of configuration settings such as GENERATE_TREEVIEW!
+# The HTML_HEADER tag can be used to specify a user-defined HTML header file for
+# each generated HTML page. If the tag is left blank doxygen will generate a
+# standard header.
+#
+# To get valid HTML the header file that includes any scripts and style sheets
+# that doxygen needs, which is dependent on the configuration options used (e.g.
+# the setting GENERATE_TREEVIEW). It is highly recommended to start with a
+# default header using
+# doxygen -w html new_header.html new_footer.html new_stylesheet.css
+# YourConfigFile
+# and then modify the file new_header.html. See also section "Doxygen usage"
+# for information on how to generate the default header that doxygen normally
+# uses.
+# Note: The header is subject to change so you typically have to regenerate the
+# default header when upgrading to a newer version of doxygen. For a description
+# of the possible markers and block names see the documentation.
+# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_HEADER =
-# The HTML_FOOTER tag can be used to specify a personal HTML footer for
-# each generated HTML page. If it is left blank doxygen will generate a
-# standard footer.
+# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
+# generated HTML page. If the tag is left blank doxygen will generate a standard
+# footer. See HTML_HEADER for more information on how to generate a default
+# footer and what special commands can be used inside the footer. See also
+# section "Doxygen usage" for information on how to generate the default footer
+# that doxygen normally uses.
+# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_FOOTER =
-# The HTML_STYLESHEET tag can be used to specify a user-defined cascading
-# style sheet that is used by each HTML page. It can be used to
-# fine-tune the look of the HTML output. If left blank doxygen will
-# generate a default style sheet. Note that it is recommended to use
-# HTML_EXTRA_STYLESHEET instead of this one, as it is more robust and this
-# tag will in the future become obsolete.
+# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style
+# sheet that is used by each HTML page. It can be used to fine-tune the look of
+# the HTML output. If left blank doxygen will generate a default style sheet.
+# See also section "Doxygen usage" for information on how to generate the style
+# sheet that doxygen normally uses.
+# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as
+# it is more robust and this tag (HTML_STYLESHEET) will in the future become
+# obsolete.
+# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_STYLESHEET =
-# The HTML_EXTRA_STYLESHEET tag can be used to specify an additional
-# user-defined cascading style sheet that is included after the standard
-# style sheets created by doxygen. Using this option one can overrule
-# certain style aspects. This is preferred over using HTML_STYLESHEET
-# since it does not replace the standard style sheet and is therefor more
-# robust against future updates. Doxygen will copy the style sheet file to
-# the output directory.
+# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined
+# cascading style sheets that are included after the standard style sheets
+# created by doxygen. Using this option one can overrule certain style aspects.
+# This is preferred over using HTML_STYLESHEET since it does not replace the
+# standard style sheet and is therefore more robust against future updates.
+# Doxygen will copy the style sheet files to the output directory.
+# Note: The order of the extra style sheet files is of importance (e.g. the last
+# style sheet in the list overrules the setting of the previous ones in the
+# list).
+# Note: Since the styling of scrollbars can currently not be overruled in
+# Webkit/Chromium, the styling will be left out of the default doxygen.css if
+# one or more extra stylesheets have been specified. So if scrollbar
+# customization is desired it has to be added explicitly. For an example see the
+# documentation.
+# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_EXTRA_STYLESHEET =
# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
# other source files which should be copied to the HTML output directory. Note
# that these files will be copied to the base HTML output directory. Use the
-# $relpath$ marker in the HTML_HEADER and/or HTML_FOOTER files to load these
-# files. In the HTML_STYLESHEET file, use the file name only. Also note that
-# the files will be copied as-is; there are no commands or markers available.
+# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these
+# files. In the HTML_STYLESHEET file, use the file name only. Also note that the
+# files will be copied as-is; there are no commands or markers available.
+# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_EXTRA_FILES =
-# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output.
-# Doxygen will adjust the colors in the style sheet and background images
-# according to this color. Hue is specified as an angle on a colorwheel,
-# see http://en.wikipedia.org/wiki/Hue for more information.
-# For instance the value 0 represents red, 60 is yellow, 120 is green,
-# 180 is cyan, 240 is blue, 300 purple, and 360 is red again.
-# The allowed range is 0 to 359.
+# The HTML_COLORSTYLE tag can be used to specify if the generated HTML output
+# should be rendered with a dark or light theme.
+# Possible values are: LIGHT always generate light mode output, DARK always
+# generate dark mode output, AUTO_LIGHT automatically set the mode according to
+# the user preference, use light mode if no preference is set (the default),
+# AUTO_DARK automatically set the mode according to the user preference, use
+# dark mode if no preference is set and TOGGLE allow to user to switch between
+# light and dark mode via a button.
+# The default value is: AUTO_LIGHT.
+# This tag requires that the tag GENERATE_HTML is set to YES.
+
+HTML_COLORSTYLE = AUTO_LIGHT
+
+# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen
+# will adjust the colors in the style sheet and background images according to
+# this color. Hue is specified as an angle on a color-wheel, see
+# https://en.wikipedia.org/wiki/Hue for more information. For instance the value
+# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300
+# purple, and 360 is red again.
+# Minimum value: 0, maximum value: 359, default value: 220.
+# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_COLORSTYLE_HUE = 220
-# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of
-# the colors in the HTML output. For a value of 0 the output will use
-# grayscales only. A value of 255 will produce the most vivid colors.
+# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors
+# in the HTML output. For a value of 0 the output will use gray-scales only. A
+# value of 255 will produce the most vivid colors.
+# Minimum value: 0, maximum value: 255, default value: 100.
+# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_COLORSTYLE_SAT = 100
-# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to
-# the luminance component of the colors in the HTML output. Values below
-# 100 gradually make the output lighter, whereas values above 100 make
-# the output darker. The value divided by 100 is the actual gamma applied,
-# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2,
-# and 100 does not change the gamma.
+# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the
+# luminance component of the colors in the HTML output. Values below 100
+# gradually make the output lighter, whereas values above 100 make the output
+# darker. The value divided by 100 is the actual gamma applied, so 80 represents
+# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not
+# change the gamma.
+# Minimum value: 40, maximum value: 240, default value: 80.
+# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_COLORSTYLE_GAMMA = 80
-# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
-# page will contain the date and time when the page was generated. Setting
-# this to NO can help when comparing the output of multiple runs.
+# If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML
+# documentation will contain a main index with vertical navigation menus that
+# are dynamically created via JavaScript. If disabled, the navigation index will
+# consists of multiple levels of tabs that are statically embedded in every HTML
+# page. Disable this option to support browsers that do not have JavaScript,
+# like the Qt help browser.
+# The default value is: YES.
+# This tag requires that the tag GENERATE_HTML is set to YES.
-HTML_TIMESTAMP = NO
+HTML_DYNAMIC_MENUS = YES
# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML
# documentation will contain sections that can be hidden and shown after the
# page has loaded.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_DYNAMIC_SECTIONS = NO
-# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of
-# entries shown in the various tree structured indices initially; the user
-# can expand and collapse entries dynamically later on. Doxygen will expand
-# the tree to such a level that at most the specified number of entries are
-# visible (unless a fully collapsed tree already exceeds this amount).
-# So setting the number of entries 1 will produce a full collapsed tree by
-# default. 0 is a special value representing an infinite number of entries
-# and will result in a full expanded tree by default.
+# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries
+# shown in the various tree structured indices initially; the user can expand
+# and collapse entries dynamically later on. Doxygen will expand the tree to
+# such a level that at most the specified number of entries are visible (unless
+# a fully collapsed tree already exceeds this amount). So setting the number of
+# entries 1 will produce a full collapsed tree by default. 0 is a special value
+# representing an infinite number of entries and will result in a full expanded
+# tree by default.
+# Minimum value: 0, maximum value: 9999, default value: 100.
+# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_INDEX_NUM_ENTRIES = 100
-# If the GENERATE_DOCSET tag is set to YES, additional index files
-# will be generated that can be used as input for Apple's Xcode 3
-# integrated development environment, introduced with OSX 10.5 (Leopard).
-# To create a documentation set, doxygen will generate a Makefile in the
-# HTML output directory. Running make will produce the docset in that
-# directory and running "make install" will install the docset in
-# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find
-# it at startup.
-# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html
-# for more information.
+# If the GENERATE_DOCSET tag is set to YES, additional index files will be
+# generated that can be used as input for Apple's Xcode 3 integrated development
+# environment (see:
+# https://developer.apple.com/xcode/), introduced with OSX 10.5 (Leopard). To
+# create a documentation set, doxygen will generate a Makefile in the HTML
+# output directory. Running make will produce the docset in that directory and
+# running make install will install the docset in
+# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at
+# startup. See https://developer.apple.com/library/archive/featuredarticles/Doxy
+# genXcode/_index.html for more information.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_HTML is set to YES.
GENERATE_DOCSET = NO
-# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the
-# feed. A documentation feed provides an umbrella under which multiple
-# documentation sets from a single provider (such as a company or product suite)
-# can be grouped.
+# This tag determines the name of the docset feed. A documentation feed provides
+# an umbrella under which multiple documentation sets from a single provider
+# (such as a company or product suite) can be grouped.
+# The default value is: Doxygen generated docs.
+# This tag requires that the tag GENERATE_DOCSET is set to YES.
DOCSET_FEEDNAME = "Doxygen generated docs"
-# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that
-# should uniquely identify the documentation set bundle. This should be a
-# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen
-# will append .docset to the name.
+# This tag determines the URL of the docset feed. A documentation feed provides
+# an umbrella under which multiple documentation sets from a single provider
+# (such as a company or product suite) can be grouped.
+# This tag requires that the tag GENERATE_DOCSET is set to YES.
+
+DOCSET_FEEDURL =
+
+# This tag specifies a string that should uniquely identify the documentation
+# set bundle. This should be a reverse domain-name style string, e.g.
+# com.mycompany.MyDocSet. Doxygen will append .docset to the name.
+# The default value is: org.doxygen.Project.
+# This tag requires that the tag GENERATE_DOCSET is set to YES.
DOCSET_BUNDLE_ID = org.doxygen.Project
-# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely
-# identify the documentation publisher. This should be a reverse domain-name
-# style string, e.g. com.mycompany.MyDocSet.documentation.
+# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify
+# the documentation publisher. This should be a reverse domain-name style
+# string, e.g. com.mycompany.MyDocSet.documentation.
+# The default value is: org.doxygen.Publisher.
+# This tag requires that the tag GENERATE_DOCSET is set to YES.
DOCSET_PUBLISHER_ID = org.doxygen.Publisher
-# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher.
+# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher.
+# The default value is: Publisher.
+# This tag requires that the tag GENERATE_DOCSET is set to YES.
DOCSET_PUBLISHER_NAME = Publisher
-# If the GENERATE_HTMLHELP tag is set to YES, additional index files
-# will be generated that can be used as input for tools like the
-# Microsoft HTML help workshop to generate a compiled HTML help file (.chm)
-# of the generated HTML documentation.
+# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three
+# additional HTML index files: index.hhp, index.hhc, and index.hhk. The
+# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop
+# on Windows. In the beginning of 2021 Microsoft took the original page, with
+# a.o. the download links, offline the HTML help workshop was already many years
+# in maintenance mode). You can download the HTML help workshop from the web
+# archives at Installation executable (see:
+# http://web.archive.org/web/20160201063255/http://download.microsoft.com/downlo
+# ad/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe).
+#
+# The HTML Help Workshop contains a compiler that can convert all HTML output
+# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML
+# files are now used as the Windows 98 help format, and will replace the old
+# Windows help format (.hlp) on all Windows platforms in the future. Compressed
+# HTML files also contain an index, a table of contents, and you can search for
+# words in the documentation. The HTML workshop also contains a viewer for
+# compressed HTML files.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_HTML is set to YES.
GENERATE_HTMLHELP = NO
-# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can
-# be used to specify the file name of the resulting .chm file. You
-# can add a path in front of the file if the result should not be
+# The CHM_FILE tag can be used to specify the file name of the resulting .chm
+# file. You can add a path in front of the file if the result should not be
# written to the html output directory.
+# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
CHM_FILE =
-# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can
-# be used to specify the location (absolute path including file name) of
-# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run
-# the HTML help compiler on the generated index.hhp.
+# The HHC_LOCATION tag can be used to specify the location (absolute path
+# including file name) of the HTML help compiler (hhc.exe). If non-empty,
+# doxygen will try to run the HTML help compiler on the generated index.hhp.
+# The file has to be specified with full path.
+# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
HHC_LOCATION =
-# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag
-# controls if a separate .chi index file is generated (YES) or that
-# it should be included in the master .chm file (NO).
+# The GENERATE_CHI flag controls if a separate .chi index file is generated
+# (YES) or that it should be included in the main .chm file (NO).
+# The default value is: NO.
+# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
GENERATE_CHI = NO
-# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING
-# is used to encode HtmlHelp index (hhk), content (hhc) and project file
-# content.
+# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc)
+# and project file content.
+# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
CHM_INDEX_ENCODING =
-# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag
-# controls whether a binary table of contents is generated (YES) or a
-# normal table of contents (NO) in the .chm file.
+# The BINARY_TOC flag controls whether a binary table of contents is generated
+# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it
+# enables the Previous and Next buttons.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
BINARY_TOC = NO
-# The TOC_EXPAND flag can be set to YES to add extra items for group members
-# to the contents of the HTML help documentation and to the tree view.
+# The TOC_EXPAND flag can be set to YES to add extra items for group members to
+# the table of contents of the HTML help documentation and to the tree view.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
TOC_EXPAND = NO
+# The SITEMAP_URL tag is used to specify the full URL of the place where the
+# generated documentation will be placed on the server by the user during the
+# deployment of the documentation. The generated sitemap is called sitemap.xml
+# and placed on the directory specified by HTML_OUTPUT. In case no SITEMAP_URL
+# is specified no sitemap is generated. For information about the sitemap
+# protocol see https://www.sitemaps.org
+# This tag requires that the tag GENERATE_HTML is set to YES.
+
+SITEMAP_URL =
+
# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and
-# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated
-# that can be used as input for Qt's qhelpgenerator to generate a
-# Qt Compressed Help (.qch) of the generated HTML documentation.
+# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that
+# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help
+# (.qch) of the generated HTML documentation.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_HTML is set to YES.
GENERATE_QHP = NO
-# If the QHG_LOCATION tag is specified, the QCH_FILE tag can
-# be used to specify the file name of the resulting .qch file.
-# The path specified is relative to the HTML output folder.
+# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify
+# the file name of the resulting .qch file. The path specified is relative to
+# the HTML output folder.
+# This tag requires that the tag GENERATE_QHP is set to YES.
QCH_FILE =
-# The QHP_NAMESPACE tag specifies the namespace to use when generating
-# Qt Help Project output. For more information please see
-# http://doc.trolltech.com/qthelpproject.html#namespace
+# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help
+# Project output. For more information please see Qt Help Project / Namespace
+# (see:
+# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace).
+# The default value is: org.doxygen.Project.
+# This tag requires that the tag GENERATE_QHP is set to YES.
QHP_NAMESPACE = org.doxygen.Project
-# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating
-# Qt Help Project output. For more information please see
-# http://doc.trolltech.com/qthelpproject.html#virtual-folders
+# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt
+# Help Project output. For more information please see Qt Help Project / Virtual
+# Folders (see:
+# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual-folders).
+# The default value is: doc.
+# This tag requires that the tag GENERATE_QHP is set to YES.
QHP_VIRTUAL_FOLDER = doc
-# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to
-# add. For more information please see
-# http://doc.trolltech.com/qthelpproject.html#custom-filters
+# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom
+# filter to add. For more information please see Qt Help Project / Custom
+# Filters (see:
+# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters).
+# This tag requires that the tag GENERATE_QHP is set to YES.
QHP_CUST_FILTER_NAME =
-# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the
-# custom filter to add. For more information please see
-# <a href="http://doc.trolltech.com/qthelpproject.html#custom-filters">
-# Qt Help Project / Custom Filters</a>.
+# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the
+# custom filter to add. For more information please see Qt Help Project / Custom
+# Filters (see:
+# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters).
+# This tag requires that the tag GENERATE_QHP is set to YES.
QHP_CUST_FILTER_ATTRS =
# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this
-# project's
-# filter section matches.
-# <a href="http://doc.trolltech.com/qthelpproject.html#filter-attributes">
-# Qt Help Project / Filter Attributes</a>.
+# project's filter section matches. Qt Help Project / Filter Attributes (see:
+# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#filter-attributes).
+# This tag requires that the tag GENERATE_QHP is set to YES.
QHP_SECT_FILTER_ATTRS =
-# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can
-# be used to specify the location of Qt's qhelpgenerator.
-# If non-empty doxygen will try to run qhelpgenerator on the generated
-# .qhp file.
+# The QHG_LOCATION tag can be used to specify the location (absolute path
+# including file name) of Qt's qhelpgenerator. If non-empty doxygen will try to
+# run qhelpgenerator on the generated .qhp file.
+# This tag requires that the tag GENERATE_QHP is set to YES.
QHG_LOCATION =
-# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files
-# will be generated, which together with the HTML files, form an Eclipse help
-# plugin. To install this plugin and make it available under the help contents
-# menu in Eclipse, the contents of the directory containing the HTML and XML
-# files needs to be copied into the plugins directory of eclipse. The name of
-# the directory within the plugins directory should be the same as
-# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before
-# the help appears.
+# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be
+# generated, together with the HTML files, they form an Eclipse help plugin. To
+# install this plugin and make it available under the help contents menu in
+# Eclipse, the contents of the directory containing the HTML and XML files needs
+# to be copied into the plugins directory of eclipse. The name of the directory
+# within the plugins directory should be the same as the ECLIPSE_DOC_ID value.
+# After copying Eclipse needs to be restarted before the help appears.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_HTML is set to YES.
GENERATE_ECLIPSEHELP = NO
-# A unique identifier for the eclipse help plugin. When installing the plugin
-# the directory name containing the HTML and XML files should also have
-# this name.
+# A unique identifier for the Eclipse help plugin. When installing the plugin
+# the directory name containing the HTML and XML files should also have this
+# name. Each documentation set should have its own identifier.
+# The default value is: org.doxygen.Project.
+# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES.
ECLIPSE_DOC_ID = org.doxygen.Project
-# The DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs)
-# at top of each HTML page. The value NO (the default) enables the index and
-# the value YES disables it. Since the tabs have the same information as the
-# navigation tree you can set this option to NO if you already set
-# GENERATE_TREEVIEW to YES.
+# If you want full control over the layout of the generated HTML pages it might
+# be necessary to disable the index and replace it with your own. The
+# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top
+# of each HTML page. A value of NO enables the index and the value YES disables
+# it. Since the tabs in the index contain the same information as the navigation
+# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_HTML is set to YES.
DISABLE_INDEX = NO
# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
-# structure should be generated to display hierarchical information.
-# If the tag value is set to YES, a side panel will be generated
-# containing a tree-like index structure (just like the one that
-# is generated for HTML Help). For this to work a browser that supports
-# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser).
-# Windows users are probably better off using the HTML help feature.
-# Since the tree basically has the same information as the tab index you
-# could consider to set DISABLE_INDEX to NO when enabling this option.
+# structure should be generated to display hierarchical information. If the tag
+# value is set to YES, a side panel will be generated containing a tree-like
+# index structure (just like the one that is generated for HTML Help). For this
+# to work a browser that supports JavaScript, DHTML, CSS and frames is required
+# (i.e. any modern browser). Windows users are probably better off using the
+# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can
+# further fine tune the look of the index (see "Fine-tuning the output"). As an
+# example, the default style sheet generated by doxygen has an example that
+# shows how to put an image at the root of the tree instead of the PROJECT_NAME.
+# Since the tree basically has the same information as the tab index, you could
+# consider setting DISABLE_INDEX to YES when enabling this option.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_HTML is set to YES.
GENERATE_TREEVIEW = NO
-# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values
-# (range [0,1..20]) that doxygen will group on one line in the generated HTML
-# documentation. Note that a value of 0 will completely suppress the enum
-# values from appearing in the overview section.
+# When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the
+# FULL_SIDEBAR option determines if the side bar is limited to only the treeview
+# area (value NO) or if it should extend to the full height of the window (value
+# YES). Setting this to YES gives a layout similar to
+# https://docs.readthedocs.io with more room for contents, but less room for the
+# project logo, title, and description. If either GENERATE_TREEVIEW or
+# DISABLE_INDEX is set to NO, this option has no effect.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_HTML is set to YES.
+
+FULL_SIDEBAR = NO
+
+# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that
+# doxygen will group on one line in the generated HTML documentation.
+#
+# Note that a value of 0 will completely suppress the enum values from appearing
+# in the overview section.
+# Minimum value: 0, maximum value: 20, default value: 4.
+# This tag requires that the tag GENERATE_HTML is set to YES.
ENUM_VALUES_PER_LINE = 4
-# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
-# used to set the initial width (in pixels) of the frame in which the tree
-# is shown.
+# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used
+# to set the initial width (in pixels) of the frame in which the tree is shown.
+# Minimum value: 0, maximum value: 1500, default value: 250.
+# This tag requires that the tag GENERATE_HTML is set to YES.
TREEVIEW_WIDTH = 250
-# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open
-# links to external symbols imported via tag files in a separate window.
+# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to
+# external symbols imported via tag files in a separate window.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_HTML is set to YES.
EXT_LINKS_IN_WINDOW = NO
-# Use this tag to change the font size of Latex formulas included
-# as images in the HTML documentation. The default is 10. Note that
-# when you change the font size after a successful doxygen run you need
-# to manually remove any form_*.png images from the HTML output directory
-# to force them to be regenerated.
+# If the OBFUSCATE_EMAILS tag is set to YES, doxygen will obfuscate email
+# addresses.
+# The default value is: YES.
+# This tag requires that the tag GENERATE_HTML is set to YES.
+
+OBFUSCATE_EMAILS = YES
+
+# If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg
+# tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see
+# https://inkscape.org) to generate formulas as SVG images instead of PNGs for
+# the HTML output. These images will generally look nicer at scaled resolutions.
+# Possible values are: png (the default) and svg (looks nicer but requires the
+# pdf2svg or inkscape tool).
+# The default value is: png.
+# This tag requires that the tag GENERATE_HTML is set to YES.
+
+HTML_FORMULA_FORMAT = png
+
+# Use this tag to change the font size of LaTeX formulas included as images in
+# the HTML documentation. When you change the font size after a successful
+# doxygen run you need to manually remove any form_*.png images from the HTML
+# output directory to force them to be regenerated.
+# Minimum value: 8, maximum value: 50, default value: 10.
+# This tag requires that the tag GENERATE_HTML is set to YES.
FORMULA_FONTSIZE = 10
-# Use the FORMULA_TRANPARENT tag to determine whether or not the images
-# generated for formulas are transparent PNGs. Transparent PNGs are
-# not supported properly for IE 6.0, but are supported on all modern browsers.
-# Note that when changing this option you need to delete any form_*.png files
-# in the HTML output before the changes have effect.
+# The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands
+# to create new LaTeX commands to be used in formulas as building blocks. See
+# the section "Including formulas" for details.
-FORMULA_TRANSPARENT = YES
+FORMULA_MACROFILE =
-# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax
-# (see https://www.mathjax.org) which uses client side Javascript for the
-# rendering instead of using prerendered bitmaps. Use this if you do not
-# have LaTeX installed or if you want to formulas look prettier in the HTML
-# output. When enabled you may also need to install MathJax separately and
-# configure the path to it using the MATHJAX_RELPATH option.
+# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see
+# https://www.mathjax.org) which uses client side JavaScript for the rendering
+# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX
+# installed or if you want to formulas look prettier in the HTML output. When
+# enabled you may also need to install MathJax separately and configure the path
+# to it using the MATHJAX_RELPATH option.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_HTML is set to YES.
USE_MATHJAX = NO
+# With MATHJAX_VERSION it is possible to specify the MathJax version to be used.
+# Note that the different versions of MathJax have different requirements with
+# regards to the different settings, so it is possible that also other MathJax
+# settings have to be changed when switching between the different MathJax
+# versions.
+# Possible values are: MathJax_2 and MathJax_3.
+# The default value is: MathJax_2.
+# This tag requires that the tag USE_MATHJAX is set to YES.
+
+MATHJAX_VERSION = MathJax_2
+
# When MathJax is enabled you can set the default output format to be used for
-# thA MathJax output. Supported types are HTML-CSS, NativeMML (i.e. MathML) and
-# SVG. The default value is HTML-CSS, which is slower, but has the best
-# compatibility.
+# the MathJax output. For more details about the output format see MathJax
+# version 2 (see:
+# http://docs.mathjax.org/en/v2.7-latest/output.html) and MathJax version 3
+# (see:
+# http://docs.mathjax.org/en/latest/web/components/output.html).
+# Possible values are: HTML-CSS (which is slower, but has the best
+# compatibility. This is the name for Mathjax version 2, for MathJax version 3
+# this will be translated into chtml), NativeMML (i.e. MathML. Only supported
+# for NathJax 2. For MathJax version 3 chtml will be used instead.), chtml (This
+# is the name for Mathjax version 3, for MathJax version 2 this will be
+# translated into HTML-CSS) and SVG.
+# The default value is: HTML-CSS.
+# This tag requires that the tag USE_MATHJAX is set to YES.
MATHJAX_FORMAT = HTML-CSS
-# When MathJax is enabled you need to specify the location relative to the
-# HTML output directory using the MATHJAX_RELPATH option. The destination
-# directory should contain the MathJax.js script. For instance, if the mathjax
-# directory is located at the same level as the HTML output directory, then
-# MATHJAX_RELPATH should be ../mathjax. The default value points to
-# the MathJax Content Delivery Network so you can quickly see the result without
-# installing MathJax.
-# However, it is strongly recommended to install a local
-# copy of MathJax from https://www.mathjax.org before deployment.
+# When MathJax is enabled you need to specify the location relative to the HTML
+# output directory using the MATHJAX_RELPATH option. The destination directory
+# should contain the MathJax.js script. For instance, if the mathjax directory
+# is located at the same level as the HTML output directory, then
+# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax
+# Content Delivery Network so you can quickly see the result without installing
+# MathJax. However, it is strongly recommended to install a local copy of
+# MathJax from https://www.mathjax.org before deployment. The default value is:
+# - in case of MathJax version 2: https://cdn.jsdelivr.net/npm/mathjax@2
+# - in case of MathJax version 3: https://cdn.jsdelivr.net/npm/mathjax@3
+# This tag requires that the tag USE_MATHJAX is set to YES.
MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest
-# The MATHJAX_EXTENSIONS tag can be used to specify one or MathJax extension
-# names that should be enabled during MathJax rendering.
+# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax
+# extension names that should be enabled during MathJax rendering. For example
+# for MathJax version 2 (see
+# https://docs.mathjax.org/en/v2.7-latest/tex.html#tex-and-latex-extensions):
+# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols
+# For example for MathJax version 3 (see
+# http://docs.mathjax.org/en/latest/input/tex/extensions/index.html):
+# MATHJAX_EXTENSIONS = ams
+# This tag requires that the tag USE_MATHJAX is set to YES.
MATHJAX_EXTENSIONS =
-# When the SEARCHENGINE tag is enabled doxygen will generate a search box
-# for the HTML output. The underlying search engine uses javascript
-# and DHTML and should work on any modern browser. Note that when using
-# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets
-# (GENERATE_DOCSET) there is already a search function so this one should
-# typically be disabled. For large projects the javascript based search engine
-# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution.
+# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces
+# of code that will be used on startup of the MathJax code. See the MathJax site
+# (see:
+# http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. For an
+# example see the documentation.
+# This tag requires that the tag USE_MATHJAX is set to YES.
+
+MATHJAX_CODEFILE =
+
+# When the SEARCHENGINE tag is enabled doxygen will generate a search box for
+# the HTML output. The underlying search engine uses javascript and DHTML and
+# should work on any modern browser. Note that when using HTML help
+# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET)
+# there is already a search function so this one should typically be disabled.
+# For large projects the javascript based search engine can be slow, then
+# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to
+# search using the keyboard; to jump to the search box use <access key> + S
+# (what the <access key> is depends on the OS and browser, but it is typically
+# <CTRL>, <ALT>/<option>, or both). Inside the search box use the <cursor down
+# key> to jump into the search results window, the results can be navigated
+# using the <cursor keys>. Press <Enter> to select an item or <escape> to cancel
+# the search. The filter options can be selected when the cursor is inside the
+# search box by pressing <Shift>+<cursor down>. Also here use the <cursor keys>
+# to select a filter and <Enter> or <escape> to activate or cancel the filter
+# option.
+# The default value is: YES.
+# This tag requires that the tag GENERATE_HTML is set to YES.
SEARCHENGINE = YES
# When the SERVER_BASED_SEARCH tag is enabled the search engine will be
-# implemented using a web server instead of a web client using Javascript.
-# There are two flavours of web server based search depending on the
-# EXTERNAL_SEARCH setting. When disabled, doxygen will generate a PHP script for
-# searching and an index file used by the script. When EXTERNAL_SEARCH is
-# enabled the indexing and searching needs to be provided by external tools.
-# See the manual for details.
+# implemented using a web server instead of a web client using JavaScript. There
+# are two flavors of web server based searching depending on the EXTERNAL_SEARCH
+# setting. When disabled, doxygen will generate a PHP script for searching and
+# an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing
+# and searching needs to be provided by external tools. See the section
+# "External Indexing and Searching" for details.
+# The default value is: NO.
+# This tag requires that the tag SEARCHENGINE is set to YES.
SERVER_BASED_SEARCH = NO
-# When EXTERNAL_SEARCH is enabled doxygen will no longer generate the PHP
+# When EXTERNAL_SEARCH tag is enabled doxygen will no longer generate the PHP
# script for searching. Instead the search results are written to an XML file
# which needs to be processed by an external indexer. Doxygen will invoke an
-# external search engine pointed to by the SEARCHENGINE_URL option to obtain
-# the search results. Doxygen ships with an example indexer (doxyindexer) and
-# search engine (doxysearch.cgi) which are based on the open source search engine
-# library Xapian. See the manual for configuration details.
+# external search engine pointed to by the SEARCHENGINE_URL option to obtain the
+# search results.
+#
+# Doxygen ships with an example indexer (doxyindexer) and search engine
+# (doxysearch.cgi) which are based on the open source search engine library
+# Xapian (see:
+# https://xapian.org/).
+#
+# See the section "External Indexing and Searching" for details.
+# The default value is: NO.
+# This tag requires that the tag SEARCHENGINE is set to YES.
EXTERNAL_SEARCH = NO
# The SEARCHENGINE_URL should point to a search engine hosted by a web server
-# which will returned the search results when EXTERNAL_SEARCH is enabled.
-# Doxygen ships with an example search engine (doxysearch) which is based on
-# the open source search engine library Xapian. See the manual for configuration
+# which will return the search results when EXTERNAL_SEARCH is enabled.
+#
+# Doxygen ships with an example indexer (doxyindexer) and search engine
+# (doxysearch.cgi) which are based on the open source search engine library
+# Xapian (see:
+# https://xapian.org/). See the section "External Indexing and Searching" for
# details.
+# This tag requires that the tag SEARCHENGINE is set to YES.
SEARCHENGINE_URL =
# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the unindexed
# search data is written to a file for indexing by an external tool. With the
# SEARCHDATA_FILE tag the name of this file can be specified.
+# The default file is: searchdata.xml.
+# This tag requires that the tag SEARCHENGINE is set to YES.
SEARCHDATA_FILE = searchdata.xml
-# When SERVER_BASED_SEARCH AND EXTERNAL_SEARCH are both enabled the
+# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the
# EXTERNAL_SEARCH_ID tag can be used as an identifier for the project. This is
# useful in combination with EXTRA_SEARCH_MAPPINGS to search through multiple
# projects and redirect the results back to the right project.
+# This tag requires that the tag SEARCHENGINE is set to YES.
EXTERNAL_SEARCH_ID =
# The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through doxygen
# projects other than the one defined by this configuration file, but that are
# all added to the same external search index. Each project needs to have a
-# unique id set via EXTERNAL_SEARCH_ID. The search mapping then maps the id
-# of to a relative location where the documentation can be found.
-# The format is: EXTRA_SEARCH_MAPPINGS = id1=loc1 id2=loc2 ...
+# unique id set via EXTERNAL_SEARCH_ID. The search mapping then maps the id of
+# to a relative location where the documentation can be found. The format is:
+# EXTRA_SEARCH_MAPPINGS = tagname1=loc1 tagname2=loc2 ...
+# This tag requires that the tag SEARCHENGINE is set to YES.
EXTRA_SEARCH_MAPPINGS =
#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
+# Configuration options related to the LaTeX output
#---------------------------------------------------------------------------
-# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
-# generate Latex output.
+# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
+# The default value is: YES.
GENERATE_LATEX = NO
-# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
-# If a relative path is entered the value of OUTPUT_DIRECTORY will be
-# put in front of it. If left blank `latex' will be used as the default path.
+# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
+# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
+# it.
+# The default directory is: latex.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
LATEX_OUTPUT =
# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be
-# invoked. If left blank `latex' will be used as the default command name.
-# Note that when enabling USE_PDFLATEX this option is only used for
-# generating bitmaps for formulas in the HTML output, but not in the
-# Makefile that is written to the output directory.
+# invoked.
+#
+# Note that when not enabling USE_PDFLATEX the default is latex when enabling
+# USE_PDFLATEX the default is pdflatex and when in the later case latex is
+# chosen this is overwritten by pdflatex. For specific output languages the
+# default can have been set differently, this depends on the implementation of
+# the output language.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
LATEX_CMD_NAME =
-# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to
-# generate index for LaTeX. If left blank `makeindex' will be used as the
-# default command name.
+# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate
+# index for LaTeX.
+# Note: This tag is used in the Makefile / make.bat.
+# See also: LATEX_MAKEINDEX_CMD for the part in the generated output file
+# (.tex).
+# The default file is: makeindex.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
MAKEINDEX_CMD_NAME =
-# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact
-# LaTeX documents. This may be useful for small projects and may help to
-# save some trees in general.
+# The LATEX_MAKEINDEX_CMD tag can be used to specify the command name to
+# generate index for LaTeX. In case there is no backslash (\) as first character
+# it will be automatically added in the LaTeX code.
+# Note: This tag is used in the generated output file (.tex).
+# See also: MAKEINDEX_CMD_NAME for the part in the Makefile / make.bat.
+# The default value is: makeindex.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
+
+LATEX_MAKEINDEX_CMD = makeindex
+
+# If the COMPACT_LATEX tag is set to YES, doxygen generates more compact LaTeX
+# documents. This may be useful for small projects and may help to save some
+# trees in general.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
COMPACT_LATEX = NO
-# The PAPER_TYPE tag can be used to set the paper type that is used
-# by the printer. Possible values are: a4, letter, legal and
-# executive. If left blank a4wide will be used.
+# The PAPER_TYPE tag can be used to set the paper type that is used by the
+# printer.
+# Possible values are: a4 (210 x 297 mm), letter (8.5 x 11 inches), legal (8.5 x
+# 14 inches) and executive (7.25 x 10.5 inches).
+# The default value is: a4.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
PAPER_TYPE = letter
-# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX
-# packages that should be included in the LaTeX output.
+# The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names
+# that should be included in the LaTeX output. The package can be specified just
+# by its name or with the correct syntax as to be used with the LaTeX
+# \usepackage command. To get the times font for instance you can specify :
+# EXTRA_PACKAGES=times or EXTRA_PACKAGES={times}
+# To use the option intlimits with the amsmath package you can specify:
+# EXTRA_PACKAGES=[intlimits]{amsmath}
+# If left blank no extra packages will be included.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
EXTRA_PACKAGES =
-# The LATEX_HEADER tag can be used to specify a personal LaTeX header for
-# the generated latex document. The header should contain everything until
-# the first chapter. If it is left blank doxygen will generate a
-# standard header. Notice: only use this tag if you know what you are doing!
+# The LATEX_HEADER tag can be used to specify a user-defined LaTeX header for
+# the generated LaTeX document. The header should contain everything until the
+# first chapter. If it is left blank doxygen will generate a standard header. It
+# is highly recommended to start with a default header using
+# doxygen -w latex new_header.tex new_footer.tex new_stylesheet.sty
+# and then modify the file new_header.tex. See also section "Doxygen usage" for
+# information on how to generate the default header that doxygen normally uses.
+#
+# Note: Only use a user-defined header if you know what you are doing!
+# Note: The header is subject to change so you typically have to regenerate the
+# default header when upgrading to a newer version of doxygen. The following
+# commands have a special meaning inside the header (and footer): For a
+# description of the possible markers and block names see the documentation.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
LATEX_HEADER =
-# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for
-# the generated latex document. The footer should contain everything after
-# the last chapter. If it is left blank doxygen will generate a
-# standard footer. Notice: only use this tag if you know what you are doing!
+# The LATEX_FOOTER tag can be used to specify a user-defined LaTeX footer for
+# the generated LaTeX document. The footer should contain everything after the
+# last chapter. If it is left blank doxygen will generate a standard footer. See
+# LATEX_HEADER for more information on how to generate a default footer and what
+# special commands can be used inside the footer. See also section "Doxygen
+# usage" for information on how to generate the default footer that doxygen
+# normally uses. Note: Only use a user-defined footer if you know what you are
+# doing!
+# This tag requires that the tag GENERATE_LATEX is set to YES.
LATEX_FOOTER =
-# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated
-# is prepared for conversion to pdf (using ps2pdf). The pdf file will
-# contain links (just like the HTML output) instead of page references
-# This makes the output suitable for online browsing using a pdf viewer.
+# The LATEX_EXTRA_STYLESHEET tag can be used to specify additional user-defined
+# LaTeX style sheets that are included after the standard style sheets created
+# by doxygen. Using this option one can overrule certain style aspects. Doxygen
+# will copy the style sheet files to the output directory.
+# Note: The order of the extra style sheet files is of importance (e.g. the last
+# style sheet in the list overrules the setting of the previous ones in the
+# list).
+# This tag requires that the tag GENERATE_LATEX is set to YES.
+
+LATEX_EXTRA_STYLESHEET =
+
+# The LATEX_EXTRA_FILES tag can be used to specify one or more extra images or
+# other source files which should be copied to the LATEX_OUTPUT output
+# directory. Note that the files will be copied as-is; there are no commands or
+# markers available.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
+
+LATEX_EXTRA_FILES =
+
+# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated is
+# prepared for conversion to PDF (using ps2pdf or pdflatex). The PDF file will
+# contain links (just like the HTML output) instead of page references. This
+# makes the output suitable for online browsing using a PDF viewer.
+# The default value is: YES.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
PDF_HYPERLINKS = YES
-# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of
-# plain latex in the generated Makefile. Set this option to YES to get a
-# higher quality PDF documentation.
+# If the USE_PDFLATEX tag is set to YES, doxygen will use the engine as
+# specified with LATEX_CMD_NAME to generate the PDF file directly from the LaTeX
+# files. Set this option to YES, to get a higher quality PDF documentation.
+#
+# See also section LATEX_CMD_NAME for selecting the engine.
+# The default value is: YES.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
USE_PDFLATEX = YES
-# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode.
-# command to the generated LaTeX files. This will instruct LaTeX to keep
-# running if errors occur, instead of asking the user for help.
-# This option is also used when generating formulas in HTML.
+# The LATEX_BATCHMODE tag ignals the behavior of LaTeX in case of an error.
+# Possible values are: NO same as ERROR_STOP, YES same as BATCH, BATCH In batch
+# mode nothing is printed on the terminal, errors are scrolled as if <return> is
+# hit at every error; missing files that TeX tries to input or request from
+# keyboard input (\read on a not open input stream) cause the job to abort,
+# NON_STOP In nonstop mode the diagnostic message will appear on the terminal,
+# but there is no possibility of user interaction just like in batch mode,
+# SCROLL In scroll mode, TeX will stop only for missing files to input or if
+# keyboard input is necessary and ERROR_STOP In errorstop mode, TeX will stop at
+# each error, asking for user intervention.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
LATEX_BATCHMODE = NO
-# If LATEX_HIDE_INDICES is set to YES then doxygen will not
-# include the index chapters (such as File Index, Compound Index, etc.)
-# in the output.
+# If the LATEX_HIDE_INDICES tag is set to YES then doxygen will not include the
+# index chapters (such as File Index, Compound Index, etc.) in the output.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
LATEX_HIDE_INDICES = NO
-# If LATEX_SOURCE_CODE is set to YES then doxygen will include
-# source code with syntax highlighting in the LaTeX output.
-# Note that which sources are shown also depends on other settings
-# such as SOURCE_BROWSER.
-
-LATEX_SOURCE_CODE = NO
-
# The LATEX_BIB_STYLE tag can be used to specify the style to use for the
-# bibliography, e.g. plainnat, or ieeetr. The default style is "plain". See
-# http://en.wikipedia.org/wiki/BibTeX for more info.
+# bibliography, e.g. plainnat, or ieeetr. See
+# https://en.wikipedia.org/wiki/BibTeX and \cite for more info.
+# The default value is: plain.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
LATEX_BIB_STYLE = plain
+# The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute)
+# path from which the emoji images will be read. If a relative path is entered,
+# it will be relative to the LATEX_OUTPUT directory. If left blank the
+# LATEX_OUTPUT directory will be used.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
+
+LATEX_EMOJI_DIRECTORY =
+
#---------------------------------------------------------------------------
-# configuration options related to the RTF output
+# Configuration options related to the RTF output
#---------------------------------------------------------------------------
-# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output
-# The RTF output is optimized for Word 97 and may not look very pretty with
-# other RTF readers or editors.
+# If the GENERATE_RTF tag is set to YES, doxygen will generate RTF output. The
+# RTF output is optimized for Word 97 and may not look too pretty with other RTF
+# readers/editors.
+# The default value is: NO.
GENERATE_RTF = NO
-# The RTF_OUTPUT tag is used to specify where the RTF docs will be put.
-# If a relative path is entered the value of OUTPUT_DIRECTORY will be
-# put in front of it. If left blank `rtf' will be used as the default path.
+# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. If a
+# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
+# it.
+# The default directory is: rtf.
+# This tag requires that the tag GENERATE_RTF is set to YES.
RTF_OUTPUT =
-# If the COMPACT_RTF tag is set to YES Doxygen generates more compact
-# RTF documents. This may be useful for small projects and may help to
-# save some trees in general.
+# If the COMPACT_RTF tag is set to YES, doxygen generates more compact RTF
+# documents. This may be useful for small projects and may help to save some
+# trees in general.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_RTF is set to YES.
COMPACT_RTF = NO
-# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated
-# will contain hyperlink fields. The RTF file will
-# contain links (just like the HTML output) instead of page references.
-# This makes the output suitable for online browsing using WORD or other
-# programs which support those fields.
-# Note: wordpad (write) and others do not support links.
+# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated will
+# contain hyperlink fields. The RTF file will contain links (just like the HTML
+# output) instead of page references. This makes the output suitable for online
+# browsing using Word or some other Word compatible readers that support those
+# fields.
+#
+# Note: WordPad (write) and others do not support links.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_RTF is set to YES.
RTF_HYPERLINKS = NO
-# Load style sheet definitions from file. Syntax is similar to doxygen's
-# config file, i.e. a series of assignments. You only have to provide
+# Load stylesheet definitions from file. Syntax is similar to doxygen's
+# configuration file, i.e. a series of assignments. You only have to provide
# replacements, missing definitions are set to their default value.
+#
+# See also section "Doxygen usage" for information on how to generate the
+# default style sheet that doxygen normally uses.
+# This tag requires that the tag GENERATE_RTF is set to YES.
RTF_STYLESHEET_FILE =
-# Set optional variables used in the generation of an rtf document.
-# Syntax is similar to doxygen's config file.
+# Set optional variables used in the generation of an RTF document. Syntax is
+# similar to doxygen's configuration file. A template extensions file can be
+# generated using doxygen -e rtf extensionFile.
+# This tag requires that the tag GENERATE_RTF is set to YES.
RTF_EXTENSIONS_FILE =
#---------------------------------------------------------------------------
-# configuration options related to the man page output
+# Configuration options related to the man page output
#---------------------------------------------------------------------------
-# If the GENERATE_MAN tag is set to YES (the default) Doxygen will
-# generate man pages
+# If the GENERATE_MAN tag is set to YES, doxygen will generate man pages for
+# classes and files.
+# The default value is: NO.
GENERATE_MAN = NO
-# The MAN_OUTPUT tag is used to specify where the man pages will be put.
-# If a relative path is entered the value of OUTPUT_DIRECTORY will be
-# put in front of it. If left blank `man' will be used as the default path.
+# The MAN_OUTPUT tag is used to specify where the man pages will be put. If a
+# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
+# it. A directory man3 will be created inside the directory specified by
+# MAN_OUTPUT.
+# The default directory is: man.
+# This tag requires that the tag GENERATE_MAN is set to YES.
MAN_OUTPUT =
-# The MAN_EXTENSION tag determines the extension that is added to
-# the generated man pages (default is the subroutine's section .3)
+# The MAN_EXTENSION tag determines the extension that is added to the generated
+# man pages. In case the manual section does not start with a number, the number
+# 3 is prepended. The dot (.) at the beginning of the MAN_EXTENSION tag is
+# optional.
+# The default value is: .3.
+# This tag requires that the tag GENERATE_MAN is set to YES.
MAN_EXTENSION =
-# If the MAN_LINKS tag is set to YES and Doxygen generates man output,
-# then it will generate one additional man file for each entity
-# documented in the real man page(s). These additional files
-# only source the real man page, but without them the man command
-# would be unable to find the correct page. The default is NO.
+# The MAN_SUBDIR tag determines the name of the directory created within
+# MAN_OUTPUT in which the man pages are placed. If defaults to man followed by
+# MAN_EXTENSION with the initial . removed.
+# This tag requires that the tag GENERATE_MAN is set to YES.
+
+MAN_SUBDIR =
+
+# If the MAN_LINKS tag is set to YES and doxygen generates man output, then it
+# will generate one additional man file for each entity documented in the real
+# man page(s). These additional files only source the real man page, but without
+# them the man command would be unable to find the correct page.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_MAN is set to YES.
MAN_LINKS = NO
#---------------------------------------------------------------------------
-# configuration options related to the XML output
+# Configuration options related to the XML output
#---------------------------------------------------------------------------
-# If the GENERATE_XML tag is set to YES Doxygen will
-# generate an XML file that captures the structure of
-# the code including all documentation.
+# If the GENERATE_XML tag is set to YES, doxygen will generate an XML file that
+# captures the structure of the code including all documentation.
+# The default value is: NO.
GENERATE_XML = NO
-# The XML_OUTPUT tag is used to specify where the XML pages will be put.
-# If a relative path is entered the value of OUTPUT_DIRECTORY will be
-# put in front of it. If left blank `xml' will be used as the default path.
+# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
+# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
+# it.
+# The default directory is: xml.
+# This tag requires that the tag GENERATE_XML is set to YES.
XML_OUTPUT = xml
-# If the XML_PROGRAMLISTING tag is set to YES Doxygen will
-# dump the program listings (including syntax highlighting
-# and cross-referencing information) to the XML output. Note that
-# enabling this will significantly increase the size of the XML output.
+# If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program
+# listings (including syntax highlighting and cross-referencing information) to
+# the XML output. Note that enabling this will significantly increase the size
+# of the XML output.
+# The default value is: YES.
+# This tag requires that the tag GENERATE_XML is set to YES.
XML_PROGRAMLISTING = YES
+# If the XML_NS_MEMB_FILE_SCOPE tag is set to YES, doxygen will include
+# namespace members in file scope as well, matching the HTML output.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_XML is set to YES.
+
+XML_NS_MEMB_FILE_SCOPE = NO
+
#---------------------------------------------------------------------------
-# configuration options for the AutoGen Definitions output
+# Configuration options related to the DOCBOOK output
#---------------------------------------------------------------------------
-# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will
-# generate an AutoGen Definitions (see autogen.sf.net) file
-# that captures the structure of the code including all
-# documentation. Note that this feature is still experimental
-# and incomplete at the moment.
+# If the GENERATE_DOCBOOK tag is set to YES, doxygen will generate Docbook files
+# that can be used to generate PDF.
+# The default value is: NO.
+
+GENERATE_DOCBOOK = NO
+
+# The DOCBOOK_OUTPUT tag is used to specify where the Docbook pages will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be put in
+# front of it.
+# The default directory is: docbook.
+# This tag requires that the tag GENERATE_DOCBOOK is set to YES.
+
+DOCBOOK_OUTPUT = docbook
+
+#---------------------------------------------------------------------------
+# Configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an
+# AutoGen Definitions (see https://autogen.sourceforge.net/) file that captures
+# the structure of the code including all documentation. Note that this feature
+# is still experimental and incomplete at the moment.
+# The default value is: NO.
GENERATE_AUTOGEN_DEF = NO
#---------------------------------------------------------------------------
-# configuration options related to the Perl module output
+# Configuration options related to the Perl module output
#---------------------------------------------------------------------------
-# If the GENERATE_PERLMOD tag is set to YES Doxygen will
-# generate a Perl module file that captures the structure of
-# the code including all documentation. Note that this
-# feature is still experimental and incomplete at the
-# moment.
+# If the GENERATE_PERLMOD tag is set to YES, doxygen will generate a Perl module
+# file that captures the structure of the code including all documentation.
+#
+# Note that this feature is still experimental and incomplete at the moment.
+# The default value is: NO.
GENERATE_PERLMOD = NO
-# If the PERLMOD_LATEX tag is set to YES Doxygen will generate
-# the necessary Makefile rules, Perl scripts and LaTeX code to be able
-# to generate PDF and DVI output from the Perl module output.
+# If the PERLMOD_LATEX tag is set to YES, doxygen will generate the necessary
+# Makefile rules, Perl scripts and LaTeX code to be able to generate PDF and DVI
+# output from the Perl module output.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_PERLMOD is set to YES.
PERLMOD_LATEX = NO
-# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be
-# nicely formatted so it can be parsed by a human reader.
-# This is useful
-# if you want to understand what is going on.
-# On the other hand, if this
-# tag is set to NO the size of the Perl module output will be much smaller
-# and Perl will parse it just the same.
+# If the PERLMOD_PRETTY tag is set to YES, the Perl module output will be nicely
+# formatted so it can be parsed by a human reader. This is useful if you want to
+# understand what is going on. On the other hand, if this tag is set to NO, the
+# size of the Perl module output will be much smaller and Perl will parse it
+# just the same.
+# The default value is: YES.
+# This tag requires that the tag GENERATE_PERLMOD is set to YES.
PERLMOD_PRETTY = YES
-# The names of the make variables in the generated doxyrules.make file
-# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX.
-# This is useful so different doxyrules.make files included by the same
-# Makefile don't overwrite each other's variables.
+# The names of the make variables in the generated doxyrules.make file are
+# prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. This is useful
+# so different doxyrules.make files included by the same Makefile don't
+# overwrite each other's variables.
+# This tag requires that the tag GENERATE_PERLMOD is set to YES.
PERLMOD_MAKEVAR_PREFIX =
@@ -1523,331 +2294,473 @@ PERLMOD_MAKEVAR_PREFIX =
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
-# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will
-# evaluate all C-preprocessor directives found in the sources and include
-# files.
+# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all
+# C-preprocessor directives found in the sources and include files.
+# The default value is: YES.
ENABLE_PREPROCESSING = YES
-# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
-# names in the source code. If set to NO (the default) only conditional
-# compilation will be performed. Macro expansion can be done in a controlled
-# way by setting EXPAND_ONLY_PREDEF to YES.
+# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names
+# in the source code. If set to NO, only conditional compilation will be
+# performed. Macro expansion can be done in a controlled way by setting
+# EXPAND_ONLY_PREDEF to YES.
+# The default value is: NO.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
MACRO_EXPANSION = YES
-# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
-# then the macro expansion is limited to the macros specified with the
-# PREDEFINED and EXPAND_AS_DEFINED tags.
+# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
+# the macro expansion is limited to the macros specified with the PREDEFINED and
+# EXPAND_AS_DEFINED tags.
+# The default value is: NO.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
EXPAND_ONLY_PREDEF = YES
-# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
-# pointed to by INCLUDE_PATH will be searched when a #include is found.
+# If the SEARCH_INCLUDES tag is set to YES, the include files in the
+# INCLUDE_PATH will be searched if a #include is found.
+# The default value is: YES.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
SEARCH_INCLUDES = YES
# The INCLUDE_PATH tag can be used to specify one or more directories that
-# contain include files that are not input files but should be processed by
-# the preprocessor.
+# contain include files that are not input files but should be processed by the
+# preprocessor. Note that the INCLUDE_PATH is not recursive, so the setting of
+# RECURSIVE has no effect here.
+# This tag requires that the tag SEARCH_INCLUDES is set to YES.
INCLUDE_PATH = ${CMAKE_SOURCE_DIR}/libgnucash/engine/
# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
# patterns (like *.h and *.hpp) to filter out the header-files in the
-# directories. If left blank, the patterns specified with FILE_PATTERNS will
-# be used.
+# directories. If left blank, the patterns specified with FILE_PATTERNS will be
+# used.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
INCLUDE_FILE_PATTERNS =
-# The PREDEFINED tag can be used to specify one or more macro names that
-# are defined before the preprocessor is started (similar to the -D option of
-# gcc). The argument of the tag is a list of macros of the form: name
-# or name=definition (no spaces). If the definition and the = are
-# omitted =1 is assumed. To prevent a macro definition from being
-# undefined via #undef or recursively expanded use the := operator
-# instead of the = operator.
+# The PREDEFINED tag can be used to specify one or more macro names that are
+# defined before the preprocessor is started (similar to the -D option of e.g.
+# gcc). The argument of the tag is a list of macros of the form: name or
+# name=definition (no spaces). If the definition and the "=" are omitted, "=1"
+# is assumed. To prevent a macro definition from being undefined via #undef or
+# recursively expanded use the := operator instead of the = operator.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
PREDEFINED =
-# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
-# this tag can be used to specify a list of macro names that should be expanded.
-# The macro definition that is found in the sources will be used.
-# Use the PREDEFINED tag if you want to use a different macro definition that
-# overrules the definition found in the source code.
+# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
+# tag can be used to specify a list of macro names that should be expanded. The
+# macro definition that is found in the sources will be used. Use the PREDEFINED
+# tag if you want to use a different macro definition that overrules the
+# definition found in the source code.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
EXPAND_AS_DEFINED = DEFINE_ENUM
-# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then
-# doxygen's preprocessor will remove all references to function-like macros
-# that are alone on a line, have an all uppercase name, and do not end with a
-# semicolon, because these will confuse the parser if not removed.
+# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
+# remove all references to function-like macros that are alone on a line, have
+# an all uppercase name, and do not end with a semicolon. Such function macros
+# are typically used for boiler-plate code, and will confuse the parser if not
+# removed.
+# The default value is: YES.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
SKIP_FUNCTION_MACROS = YES
#---------------------------------------------------------------------------
-# Configuration::additions related to external references
+# Configuration options related to external references
#---------------------------------------------------------------------------
-# The TAGFILES option can be used to specify one or more tagfiles. For each
-# tag file the location of the external documentation should be added. The
-# format of a tag file without this location is as follows:
-#
+# The TAGFILES tag can be used to specify one or more tag files. For each tag
+# file the location of the external documentation should be added. The format of
+# a tag file without this location is as follows:
# TAGFILES = file1 file2 ...
# Adding location for the tag files is done as follows:
-#
# TAGFILES = file1=loc1 "file2 = loc2" ...
-# where "loc1" and "loc2" can be relative or absolute paths
-# or URLs. Note that each tag file must have a unique name (where the name does
-# NOT include the path). If a tag file is not located in the directory in which
-# doxygen is run, you must also specify the path to the tagfile here.
+# where loc1 and loc2 can be relative or absolute paths or URLs. See the
+# section "Linking to external documentation" for more information about the use
+# of tag files.
+# Note: Each tag file must have a unique name (where the name does NOT include
+# the path). If a tag file is not located in the directory in which doxygen is
+# run, you must also specify the path to the tagfile here.
TAGFILES =
-# When a file name is specified after GENERATE_TAGFILE, doxygen will create
-# a tag file that is based on the input files it reads.
+# When a file name is specified after GENERATE_TAGFILE, doxygen will create a
+# tag file that is based on the input files it reads. See section "Linking to
+# external documentation" for more information about the usage of tag files.
GENERATE_TAGFILE =
-# If the ALLEXTERNALS tag is set to YES all external classes will be listed
-# in the class index. If set to NO only the inherited external classes
-# will be listed.
+# If the ALLEXTERNALS tag is set to YES, all external class will be listed in
+# the class index. If set to NO, only the inherited external classes will be
+# listed.
+# The default value is: NO.
ALLEXTERNALS = NO
-# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed
-# in the modules index. If set to NO, only the current project's groups will
-# be listed.
+# If the EXTERNAL_GROUPS tag is set to YES, all external groups will be listed
+# in the modules index. If set to NO, only the current project's groups will be
+# listed.
+# The default value is: YES.
EXTERNAL_GROUPS = YES
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool
-#---------------------------------------------------------------------------
-
-# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will
-# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base
-# or super classes. Setting the tag to NO turns the diagrams off. Note that
-# this option also works with HAVE_DOT disabled, but it is recommended to
-# install and use dot, since it yields more powerful graphs.
+# If the EXTERNAL_PAGES tag is set to YES, all external pages will be listed in
+# the related pages index. If set to NO, only the current project's pages will
+# be listed.
+# The default value is: YES.
-CLASS_DIAGRAMS = YES
+EXTERNAL_PAGES = YES
-# You can define message sequence charts within doxygen comments using the \msc
-# command. Doxygen will then run the mscgen tool (see
-# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the
-# documentation. The MSCGEN_PATH tag allows you to specify the directory where
-# the mscgen tool resides. If left empty the tool is assumed to be found in the
-# default search path.
-
-MSCGEN_PATH =
+#---------------------------------------------------------------------------
+# Configuration options related to diagram generator tools
+#---------------------------------------------------------------------------
-# If set to YES, the inheritance and collaboration graphs will hide
-# inheritance and usage relations if the target is undocumented
-# or is not a class.
+# If set to YES the inheritance and collaboration graphs will hide inheritance
+# and usage relations if the target is undocumented or is not a class.
+# The default value is: YES.
HIDE_UNDOC_RELATIONS = YES
# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
-# available from the path. This tool is part of Graphviz, a graph visualization
-# toolkit from AT&T and Lucent Bell Labs. The other options in this section
-# have no effect if this option is set to NO (the default)
+# available from the path. This tool is part of Graphviz (see:
+# https://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent
+# Bell Labs. The other options in this section have no effect if this option is
+# set to NO
+# The default value is: NO.
HAVE_DOT = NO
-# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is
-# allowed to run in parallel. When set to 0 (the default) doxygen will
-# base this on the number of processors available in the system. You can set it
-# explicitly to a value larger than 0 to get control over the balance
-# between CPU load and processing speed.
+# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed
+# to run in parallel. When set to 0 doxygen will base this on the number of
+# processors available in the system. You can set it explicitly to a value
+# larger than 0 to get control over the balance between CPU load and processing
+# speed.
+# Minimum value: 0, maximum value: 32, default value: 0.
+# This tag requires that the tag HAVE_DOT is set to YES.
DOT_NUM_THREADS = 0
-# By default doxygen will use the Helvetica font for all dot files that
-# doxygen generates. When you want a differently looking font you can specify
-# the font name using DOT_FONTNAME. You need to make sure dot is able to find
-# the font, which can be done by putting it in a standard location or by setting
-# the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the
-# directory containing the font.
+# DOT_COMMON_ATTR is common attributes for nodes, edges and labels of
+# subgraphs. When you want a differently looking font in the dot files that
+# doxygen generates you can specify fontname, fontcolor and fontsize attributes.
+# For details please see <a href=https://graphviz.org/doc/info/attrs.html>Node,
+# Edge and Graph Attributes specification</a> You need to make sure dot is able
+# to find the font, which can be done by putting it in a standard location or by
+# setting the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the
+# directory containing the font. Default graphviz fontsize is 14.
+# The default value is: fontname=Helvetica,fontsize=10.
+# This tag requires that the tag HAVE_DOT is set to YES.
+
+DOT_COMMON_ATTR = "fontname=Helvetica,fontsize=10"
+
+# DOT_EDGE_ATTR is concatenated with DOT_COMMON_ATTR. For elegant style you can
+# add 'arrowhead=open, arrowtail=open, arrowsize=0.5'. <a
+# href=https://graphviz.org/doc/info/arrows.html>Complete documentation about
+# arrows shapes.</a>
+# The default value is: labelfontname=Helvetica,labelfontsize=10.
+# This tag requires that the tag HAVE_DOT is set to YES.
-DOT_FONTNAME =
+DOT_EDGE_ATTR = "labelfontname=Helvetica,labelfontsize=10"
-# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs.
-# The default size is 10pt.
+# DOT_NODE_ATTR is concatenated with DOT_COMMON_ATTR. For view without boxes
+# around nodes set 'shape=plain' or 'shape=plaintext' <a
+# href=https://www.graphviz.org/doc/info/shapes.html>Shapes specification</a>
+# The default value is: shape=box,height=0.2,width=0.4.
+# This tag requires that the tag HAVE_DOT is set to YES.
-DOT_FONTSIZE = 10
+DOT_NODE_ATTR = "shape=box,height=0.2,width=0.4"
-# By default doxygen will tell dot to use the Helvetica font.
-# If you specify a different font using DOT_FONTNAME you can use DOT_FONTPATH to
-# set the path where dot can find it.
+# You can set the path where dot can find font specified with fontname in
+# DOT_COMMON_ATTR and others dot attributes.
+# This tag requires that the tag HAVE_DOT is set to YES.
DOT_FONTPATH =
-# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen
-# will generate a graph for each documented class showing the direct and
-# indirect inheritance relations. Setting this tag to YES will force the
-# CLASS_DIAGRAMS tag to NO.
+# If the CLASS_GRAPH tag is set to YES or GRAPH or BUILTIN then doxygen will
+# generate a graph for each documented class showing the direct and indirect
+# inheritance relations. In case the CLASS_GRAPH tag is set to YES or GRAPH and
+# HAVE_DOT is enabled as well, then dot will be used to draw the graph. In case
+# the CLASS_GRAPH tag is set to YES and HAVE_DOT is disabled or if the
+# CLASS_GRAPH tag is set to BUILTIN, then the built-in generator will be used.
+# If the CLASS_GRAPH tag is set to TEXT the direct and indirect inheritance
+# relations will be shown as texts / links.
+# Possible values are: NO, YES, TEXT, GRAPH and BUILTIN.
+# The default value is: YES.
CLASS_GRAPH = YES
-# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen
-# will generate a graph for each documented class showing the direct and
-# indirect implementation dependencies (inheritance, containment, and
-# class references variables) of the class with other documented classes.
+# If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a
+# graph for each documented class showing the direct and indirect implementation
+# dependencies (inheritance, containment, and class references variables) of the
+# class with other documented classes.
+# The default value is: YES.
+# This tag requires that the tag HAVE_DOT is set to YES.
COLLABORATION_GRAPH = YES
-# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen
-# will generate a graph for groups, showing the direct groups dependencies
+# If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for
+# groups, showing the direct groups dependencies. See also the chapter Grouping
+# in the manual.
+# The default value is: YES.
+# This tag requires that the tag HAVE_DOT is set to YES.
GROUP_GRAPHS = YES
-# If the UML_LOOK tag is set to YES doxygen will generate inheritance and
+# If the UML_LOOK tag is set to YES, doxygen will generate inheritance and
# collaboration diagrams in a style similar to the OMG's Unified Modeling
# Language.
+# The default value is: NO.
+# This tag requires that the tag HAVE_DOT is set to YES.
UML_LOOK = NO
-# If the UML_LOOK tag is enabled, the fields and methods are shown inside
-# the class node. If there are many fields or methods and many nodes the
-# graph may become too big to be useful. The UML_LIMIT_NUM_FIELDS
-# threshold limits the number of items for each type to make the size more
-# manageable. Set this to 0 for no limit. Note that the threshold may be
-# exceeded by 50% before the limit is enforced.
+# If the UML_LOOK tag is enabled, the fields and methods are shown inside the
+# class node. If there are many fields or methods and many nodes the graph may
+# become too big to be useful. The UML_LIMIT_NUM_FIELDS threshold limits the
+# number of items for each type to make the size more manageable. Set this to 0
+# for no limit. Note that the threshold may be exceeded by 50% before the limit
+# is enforced. So when you set the threshold to 10, up to 15 fields may appear,
+# but if the number exceeds 15, the total amount of fields shown is limited to
+# 10.
+# Minimum value: 0, maximum value: 100, default value: 10.
+# This tag requires that the tag UML_LOOK is set to YES.
UML_LIMIT_NUM_FIELDS = 10
-# If set to YES, the inheritance and collaboration graphs will show the
-# relations between templates and their instances.
+# If the DOT_UML_DETAILS tag is set to NO, doxygen will show attributes and
+# methods without types and arguments in the UML graphs. If the DOT_UML_DETAILS
+# tag is set to YES, doxygen will add type and arguments for attributes and
+# methods in the UML graphs. If the DOT_UML_DETAILS tag is set to NONE, doxygen
+# will not generate fields with class member information in the UML graphs. The
+# class diagrams will look similar to the default class diagrams but using UML
+# notation for the relationships.
+# Possible values are: NO, YES and NONE.
+# The default value is: NO.
+# This tag requires that the tag UML_LOOK is set to YES.
+
+DOT_UML_DETAILS = NO
+
+# The DOT_WRAP_THRESHOLD tag can be used to set the maximum number of characters
+# to display on a single line. If the actual line length exceeds this threshold
+# significantly it will wrapped across multiple lines. Some heuristics are apply
+# to avoid ugly line breaks.
+# Minimum value: 0, maximum value: 1000, default value: 17.
+# This tag requires that the tag HAVE_DOT is set to YES.
+
+DOT_WRAP_THRESHOLD = 17
+
+# If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and
+# collaboration graphs will show the relations between templates and their
+# instances.
+# The default value is: NO.
+# This tag requires that the tag HAVE_DOT is set to YES.
TEMPLATE_RELATIONS = YES
-# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT
-# tags are set to YES then doxygen will generate a graph for each documented
-# file showing the direct and indirect include dependencies of the file with
-# other documented files.
+# If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to
+# YES then doxygen will generate a graph for each documented file showing the
+# direct and indirect include dependencies of the file with other documented
+# files.
+# The default value is: YES.
+# This tag requires that the tag HAVE_DOT is set to YES.
INCLUDE_GRAPH = YES
-# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and
-# HAVE_DOT tags are set to YES then doxygen will generate a graph for each
-# documented header file showing the documented files that directly or
-# indirectly include this file.
+# If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are
+# set to YES then doxygen will generate a graph for each documented file showing
+# the direct and indirect include dependencies of the file with other documented
+# files.
+# The default value is: YES.
+# This tag requires that the tag HAVE_DOT is set to YES.
INCLUDED_BY_GRAPH = YES
-# If the CALL_GRAPH and HAVE_DOT options are set to YES then
-# doxygen will generate a call dependency graph for every global function
-# or class method. Note that enabling this option will significantly increase
-# the time of a run. So in most cases it will be better to enable call graphs
-# for selected functions only using the \callgraph command.
+# If the CALL_GRAPH tag is set to YES then doxygen will generate a call
+# dependency graph for every global function or class method.
+#
+# Note that enabling this option will significantly increase the time of a run.
+# So in most cases it will be better to enable call graphs for selected
+# functions only using the \callgraph command. Disabling a call graph can be
+# accomplished by means of the command \hidecallgraph.
+# The default value is: NO.
+# This tag requires that the tag HAVE_DOT is set to YES.
CALL_GRAPH = NO
-# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then
-# doxygen will generate a caller dependency graph for every global function
-# or class method. Note that enabling this option will significantly increase
-# the time of a run. So in most cases it will be better to enable caller
-# graphs for selected functions only using the \callergraph command.
+# If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller
+# dependency graph for every global function or class method.
+#
+# Note that enabling this option will significantly increase the time of a run.
+# So in most cases it will be better to enable caller graphs for selected
+# functions only using the \callergraph command. Disabling a caller graph can be
+# accomplished by means of the command \hidecallergraph.
+# The default value is: NO.
+# This tag requires that the tag HAVE_DOT is set to YES.
CALLER_GRAPH = NO
-# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen
-# will generate a graphical hierarchy of all classes instead of a textual one.
+# If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical
+# hierarchy of all classes instead of a textual one.
+# The default value is: YES.
+# This tag requires that the tag HAVE_DOT is set to YES.
GRAPHICAL_HIERARCHY = YES
-# If the DIRECTORY_GRAPH and HAVE_DOT tags are set to YES
-# then doxygen will show the dependencies a directory has on other directories
-# in a graphical way. The dependency relations are determined by the #include
-# relations between the files in the directories.
+# If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the
+# dependencies a directory has on other directories in a graphical way. The
+# dependency relations are determined by the #include relations between the
+# files in the directories.
+# The default value is: YES.
+# This tag requires that the tag HAVE_DOT is set to YES.
DIRECTORY_GRAPH = YES
+# The DIR_GRAPH_MAX_DEPTH tag can be used to limit the maximum number of levels
+# of child directories generated in directory dependency graphs by dot.
+# Minimum value: 1, maximum value: 25, default value: 1.
+# This tag requires that the tag DIRECTORY_GRAPH is set to YES.
+
+DIR_GRAPH_MAX_DEPTH = 1
+
# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images
-# generated by dot. Possible values are svg, png, jpg, or gif.
-# If left blank png will be used. If you choose svg you need to set
-# HTML_FILE_EXTENSION to xhtml in order to make the SVG files
-# visible in IE 9+ (other browsers do not have this requirement).
+# generated by dot. For an explanation of the image formats see the section
+# output formats in the documentation of the dot tool (Graphviz (see:
+# https://www.graphviz.org/)).
+# Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order
+# to make the SVG files visible in IE 9+ (other browsers do not have this
+# requirement).
+# Possible values are: png, jpg, gif, svg, png:gd, png:gd:gd, png:cairo,
+# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and
+# png:gdiplus:gdiplus.
+# The default value is: png.
+# This tag requires that the tag HAVE_DOT is set to YES.
DOT_IMAGE_FORMAT = png
# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
# enable generation of interactive SVG images that allow zooming and panning.
-# Note that this requires a modern browser other than Internet Explorer.
-# Tested and working are Firefox, Chrome, Safari, and Opera. For IE 9+ you
-# need to set HTML_FILE_EXTENSION to xhtml in order to make the SVG files
-# visible. Older versions of IE do not have SVG support.
+#
+# Note that this requires a modern browser other than Internet Explorer. Tested
+# and working are Firefox, Chrome, Safari, and Opera.
+# Note: For IE 9+ you need to set HTML_FILE_EXTENSION to xhtml in order to make
+# the SVG files visible. Older versions of IE do not have SVG support.
+# The default value is: NO.
+# This tag requires that the tag HAVE_DOT is set to YES.
INTERACTIVE_SVG = NO
-# The tag DOT_PATH can be used to specify the path where the dot tool can be
+# The DOT_PATH tag can be used to specify the path where the dot tool can be
# found. If left blank, it is assumed the dot tool can be found in the path.
+# This tag requires that the tag HAVE_DOT is set to YES.
DOT_PATH =
# The DOTFILE_DIRS tag can be used to specify one or more directories that
-# contain dot files that are included in the documentation (see the
-# \dotfile command).
+# contain dot files that are included in the documentation (see the \dotfile
+# command).
+# This tag requires that the tag HAVE_DOT is set to YES.
DOTFILE_DIRS =
-# The MSCFILE_DIRS tag can be used to specify one or more directories that
-# contain msc files that are included in the documentation (see the
-# \mscfile command).
+# You can include diagrams made with dia in doxygen documentation. Doxygen will
+# then run dia to produce the diagram and insert it in the documentation. The
+# DIA_PATH tag allows you to specify the directory where the dia binary resides.
+# If left empty dia is assumed to be found in the default search path.
-MSCFILE_DIRS =
+DIA_PATH =
+
+# The DIAFILE_DIRS tag can be used to specify one or more directories that
+# contain dia files that are included in the documentation (see the \diafile
+# command).
+
+DIAFILE_DIRS =
+
+# When using plantuml, the PLANTUML_JAR_PATH tag should be used to specify the
+# path where java can find the plantuml.jar file or to the filename of jar file
+# to be used. If left blank, it is assumed PlantUML is not used or called during
+# a preprocessing step. Doxygen will generate a warning when it encounters a
+# \startuml command in this case and will not generate output for the diagram.
+
+PLANTUML_JAR_PATH =
+
+# When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a
+# configuration file for plantuml.
+
+PLANTUML_CFG_FILE =
+
+# When using plantuml, the specified paths are searched for files specified by
+# the !include statement in a plantuml block.
-# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of
-# nodes that will be shown in the graph. If the number of nodes in a graph
-# becomes larger than this value, doxygen will truncate the graph, which is
-# visualized by representing a node as a red box. Note that doxygen if the
-# number of direct children of the root node in a graph is already larger than
-# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note
-# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH.
+PLANTUML_INCLUDE_PATH =
+
+# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes
+# that will be shown in the graph. If the number of nodes in a graph becomes
+# larger than this value, doxygen will truncate the graph, which is visualized
+# by representing a node as a red box. Note that doxygen if the number of direct
+# children of the root node in a graph is already larger than
+# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note that
+# the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH.
+# Minimum value: 0, maximum value: 10000, default value: 50.
+# This tag requires that the tag HAVE_DOT is set to YES.
DOT_GRAPH_MAX_NODES = 50
-# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the
-# graphs generated by dot. A depth value of 3 means that only nodes reachable
-# from the root by following a path via at most 3 edges will be shown. Nodes
-# that lay further from the root node will be omitted. Note that setting this
-# option to 1 or 2 may greatly reduce the computation time needed for large
-# code bases. Also note that the size of a graph can be further restricted by
+# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs
+# generated by dot. A depth value of 3 means that only nodes reachable from the
+# root by following a path via at most 3 edges will be shown. Nodes that lay
+# further from the root node will be omitted. Note that setting this option to 1
+# or 2 may greatly reduce the computation time needed for large code bases. Also
+# note that the size of a graph can be further restricted by
# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction.
+# Minimum value: 0, maximum value: 1000, default value: 0.
+# This tag requires that the tag HAVE_DOT is set to YES.
MAX_DOT_GRAPH_DEPTH = 0
-# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
-# background. This is disabled by default, because dot on Windows does not
-# seem to support this out of the box. Warning: Depending on the platform used,
-# enabling this option may lead to badly anti-aliased labels on the edges of
-# a graph (i.e. they become hard to read).
-
-DOT_TRANSPARENT = NO
-
-# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output
+# Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output
# files in one run (i.e. multiple -o and -T options on the command line). This
-# makes dot run faster, but since only newer versions of dot (>1.8.10)
-# support this, this feature is disabled by default.
+# makes dot run faster, but since only newer versions of dot (>1.8.10) support
+# this, this feature is disabled by default.
+# The default value is: NO.
+# This tag requires that the tag HAVE_DOT is set to YES.
DOT_MULTI_TARGETS = NO
-# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
-# generate a legend page explaining the meaning of the various boxes and
-# arrows in the dot generated graphs.
+# If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page
+# explaining the meaning of the various boxes and arrows in the dot generated
+# graphs.
+# Note: This tag requires that UML_LOOK isn't set, i.e. the doxygen internal
+# graphical representation for inheritance and collaboration diagrams is used.
+# The default value is: YES.
+# This tag requires that the tag HAVE_DOT is set to YES.
GENERATE_LEGEND = YES
-# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will
-# remove the intermediate dot files that are used to generate
-# the various graphs.
+# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate
+# files that are used to generate the various graphs.
+#
+# Note: This setting is not only used for dot files but also for msc temporary
+# files.
+# The default value is: YES.
DOT_CLEANUP = YES
-# GObject code frequently hides the definition of structs in private headers and
-# typedefs them in public declarations. TYPEDEF_HIDES_STRUCT prevents leaking
-# the private names into the documentation.
+# You can define message sequence charts within doxygen comments using the \msc
+# command. If the MSCGEN_TOOL tag is left empty (the default), then doxygen will
+# use a built-in version of mscgen tool to produce the charts. Alternatively,
+# the MSCGEN_TOOL tag can also specify the name an external tool. For instance,
+# specifying prog as the value, doxygen will call the tool as prog -T
+# <outfile_format> -o <outputfile> <inputfile>. The external tool should support
+# output file formats "png", "eps", "svg", and "ismap".
+
+MSCGEN_TOOL =
-TYPEDEF_HIDES_STRUCT = YES
+# The MSCFILE_DIRS tag can be used to specify one or more directories that
+# contain msc files that are included in the documentation (see the \mscfile
+# command).
+MSCFILE_DIRS =
commit 005112954c2bf8fba97ca3c154871956ec02510a
Author: Geert Janssens <geert at kobaltwit.be>
Date: Mon May 20 18:49:19 2024 +0200
Some cleanup of the doxygen main page
diff --git a/libgnucash/doc/doxygen_main_page.c b/libgnucash/doc/doxygen_main_page.c
index ca0462a70f..3dc474dedd 100644
--- a/libgnucash/doc/doxygen_main_page.c
+++ b/libgnucash/doc/doxygen_main_page.c
@@ -2,26 +2,26 @@
This is the new developer and design manual for GnuCash.
-\section maindocs Documentation Sections.
+\section maindocs Documentation Sections
The documentation is organised in a rough sequence:
-# \ref manualguide Start with the main GnuCash manual.
--# \ref doxylist Individual topic overviews, linked into the
- full API reference for each topic, generated from source code.
+-# \ref highlevel Pages that cover topics at a higher level. Most also have
+ links to the full API reference they relate to.
-# \ref maingeneral How to work with Doxygen in your own code.
-\subsection manualguide External documentation.
+\section manualguide External documentation
Please refer to the main
<a href="https://www.gnucash.org/docs.phtml">documentation
page</a> on the gnucash website which includes links to the
GnuCash Manual and the Concepts Guide in various formats.
-\section doxylist Doxygen overviews.
+\section highlevel Highlevel overviews
-Where possible, each overview is dated - take care to review older texts
-in relation to existing code.
+Pages that cover topics at a higher level. Most also have
+links to the full API reference they relate to.
- \ref deprecated
- \ref loanhandling
@@ -30,25 +30,11 @@ in relation to existing code.
- \ref python_bindings_page
- \ref todo
-Each overview in this section is generated directly from the
-source files using Doxygen but some topics need updating.
-
-\section maingeneral General Doxygen help.
+\section maingeneral General Doxygen help
- \ref tipshints
- \ref reference
-- \ref stylediscussion
-*/
-/* The following section links were removed from the overview section
- * because there are no corresponding sections anywhere in
- * source. Aside from networkoverview, whose intent is obscure, it
- * would be good to have them at some point.
-
-- networkoverview
-- backenderrors
-- plugindesign
-- backendapi
*/
/********************************************************************\
@@ -91,22 +77,15 @@ page title itself.
/** \section hacking Hacking on this documentation
There is the beginning of a style guide for documenting under
-\ref tipshints.
+\ref tipshints
-The Book Merge files are an attempt to document "by the book".
-\ref BookMerge\n
Feel free to start documenting or playing with doxygen configuration.
This main page can be found in src/doc/doxygen_main_page.c .
-Each doxygen section must be within a single comment block although
-large comment blocks can be split into separate pages:
-\ref stylediscussion.
-
This main page is just an introduction to doxygen markup, see the
Doxygen manual for the full command set.
- \ref tipshints Tips and hints for using doxygen
-- \ref stylediscussion Long comments, pages, editors
- \ref reference Links to the Doxygen manual
Code snippets need special handling in the text overviews. Change all
@@ -122,7 +101,6 @@ of normal C files.
\page tipshints Useful tips for doxygen in C files
- \ref index Introduction
- - \ref stylediscussion Long comments, pages, editors
- \ref reference The Doxygen manual
\section tips An introduction to doxygen markup
@@ -190,40 +168,11 @@ doxywizard doxygen.cfg &
*/
-/** \page stylediscussion Style discussion
-
-- \ref index Introduction
-- \ref tipshints Tips and hints for using doxygen
-- \ref reference Links to the Doxygen manual
-
-[codehelpgpg 2004-07-25] Doxygen now copes with addgroup and this page
-can be handled more easily by splitting the old single comment into repeated
-comments, split into pages. I've worked on doxygen files in Kate, KWrite and XCode (MacOSX) and
-the comment highlighting works fine. If you do have problems, particularly when
-you start a new line within an existing comment, enter a character at the end of
-the last highlighted line to refresh the highlighting. Some editors have a specific
-refresh option.
-
-[cstim 2003-03-25] The "Data Structures" page of doxygen doesn't show
-anything useful for GnuCash. Obviously doxygen only accepts "real" C
-struct definitions for inclusion on that page. However, all GnuCash
-data structures are defined somewhere in private headers, and only the
-typedefs are publicly visible. Isn't there a way to have doxygen
-show the documentation for the <i>typedefs</i> on the "Data
-Structures" page? Unfortunately I don't know how.
-
-[codehelpgpg 2004-07-25] Yes, there is a way of linking to these data structures.
-Make sure that the private header is included in the documentation by including a
-\\file command in the private header file. Then include a short doxygen comment above
-the declaration. Doxygen will accept both valid C struct definition formats.
-
-*/
-
/** \page reference Doxygen reference documentation
- \ref index Introduction
- \ref tipshints Tips and hints for using doxygen
-- \ref stylediscussion Long comments, pages, editors
+
The Doxygen web site (https://www.stack.nl/~dimitri/doxygen/ [DEAD LINK]) has a
complete user manual. For the impatient, here are the most
commit 39aa5f9c094c41e1af0e06cb0ebb87c5043d9385
Author: Geert Janssens <geert at kobaltwit.be>
Date: Mon May 20 17:03:30 2024 +0200
Remove texi design document in engine
It's extremely out of date and we no longer use it to keep track
of our design decisions and suggestions.
Only a section on KVP policy has been move into kvp_doc.txt
as it may make sense there.
diff --git a/.gitignore b/.gitignore
index 588496ecf9..8b6aa164f1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -96,11 +96,6 @@ libgnucash/core-utils/test/test-gnc-uri-utils
libgnucash/core-utils/test/test-resolve-file-path
libgnucash/doc/doxygen.cfg
libgnucash/doc/doxygen.log
-libgnucash/doc/design/gnucash-design.info
-libgnucash/doc/design/mdate-sh
-libgnucash/doc/design/stamp-vti
-libgnucash/doc/design/texinfo.tex
-libgnucash/doc/design/version.texi
libgnucash/doc/html/
libgnucash/engine/gncla-dir.h
libgnucash/engine/gnucash
diff --git a/HACKING b/HACKING
index 36a63b0367..ccbea4bef5 100644
--- a/HACKING
+++ b/HACKING
@@ -10,11 +10,6 @@ In addition to this file, you should read the README file, which
explains the details of getting the git source, building GnuCash,
and creating patches for submission.
-The src/doc/design directory contains a preliminary design document
-which you should read as well. You should also feel free to hack on
-the design document.
-
-
Coding Style Conventions
------------------------
Please refer to https://wiki.gnucash.org/wiki/CodingStandard.
diff --git a/README.dependencies b/README.dependencies
index 018d1620d3..e748b8b176 100644
--- a/README.dependencies
+++ b/README.dependencies
@@ -105,13 +105,6 @@ Libraries/Deps
to the main menu bar instead
of one on the window.
- makeinfo Not really needed, it
- just builds the
- mostly obsolete
- design documentation
- (superceded for the
- most part in Doxygen
- docs).
doxygen For building the Doxygen API
documentation.
diff --git a/bindings/guile/date-utilities.scm b/bindings/guile/date-utilities.scm
index d5df140634..3b0f009883 100644
--- a/bindings/guile/date-utilities.scm
+++ b/bindings/guile/date-utilities.scm
@@ -690,9 +690,7 @@ Defaulting to today."))
(current-time))
-;; There is no GNC:RELATIVE-DATES list like the one mentioned in
-;; gnucash-design.info, is there? Here are the currently defined
-;; items, loosely grouped.
+;; Here are the currently defined items, loosely grouped.
;;today
;;start-cal-year end-cal-year start-prev-year end-prev-year
;;start-this-month end-this-month start-prev-month end-prev-month
diff --git a/libgnucash/doc/CMakeLists.txt b/libgnucash/doc/CMakeLists.txt
index ffac542008..a28be64027 100644
--- a/libgnucash/doc/CMakeLists.txt
+++ b/libgnucash/doc/CMakeLists.txt
@@ -1,6 +1,3 @@
-if (NOT WIN32)
- add_subdirectory(design)
-endif()
add_subdirectory(xml)
set(doc_FILES
diff --git a/libgnucash/doc/design/CMakeLists.txt b/libgnucash/doc/design/CMakeLists.txt
deleted file mode 100644
index 17a91748c1..0000000000
--- a/libgnucash/doc/design/CMakeLists.txt
+++ /dev/null
@@ -1,44 +0,0 @@
-
-set(gnucash_design_TEXINFOS
- component-manager.texi
- concept-index.texi
- engine.texi
- fdl.texi
- function-index.texi
- intro.texi
- register.texi
- reports.texi
- top-level.texi
- type-index.texi
- user-preferences.texi
-)
-
- execute_process(COMMAND date +%e OUTPUT_VARIABLE CURRENT_DATE OUTPUT_STRIP_TRAILING_WHITESPACE)
- execute_process(COMMAND date +%B OUTPUT_VARIABLE CURRENT_MONTH OUTPUT_STRIP_TRAILING_WHITESPACE)
- execute_process(COMMAND date +%Y OUTPUT_VARIABLE CURRENT_YEAR OUTPUT_STRIP_TRAILING_WHITESPACE)
-set(UPDATED "${CURRENT_DATE} ${CURRENT_MONTH} ${CURRENT_YEAR}")
-set(UPDATED_MONTH "${CURRENT_MONTH} ${CURRENT_YEAR}")
-
-set(VERSION_TEXI_IN
- "@set UPDATED ${UPDATED}
- at set UPDATED-MONTH ${UPDATED_MONTH}
- at set EDITION ${PROJECT_VERSION}
- at set VERSION ${PROJECT_VERSION}
-")
-
-file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/version.texi ${VERSION_TEXI_IN})
-file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/stamp-vti ${VERSION_TEXI_IN})
-
-file(TO_NATIVE_PATH "${CMAKE_CURRENT_BINARY_DIR}" TEXI_BINARY_DIR)
-file(TO_NATIVE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/gnucash-design.texi" TEXI_SOURCE_FILE)
-find_program(MAKEINFO makeinfo)
-if (NOT ${MAKEINFO} STREQUAL "MAKEINFO-NOTFOUND")
- add_custom_command(
- OUTPUT gnucash-design.info
- COMMAND ${MAKEINFO} -I ${TEXI_BINARY_DIR} ${TEXI_SOURCE_FILE}
- DEPENDS ${gnucash_design_TEXINFOS}
- )
-endif()
-dist_add_generated (${BUILDING_FROM_VCS} gnucash-design.info)
-
-set_dist_list(doc_design_DIST CMakeLists.txt gnucash-design.texi ${gnucash_design_TEXINFOS})
diff --git a/libgnucash/doc/design/component-manager.texi b/libgnucash/doc/design/component-manager.texi
deleted file mode 100644
index 76be7917e0..0000000000
--- a/libgnucash/doc/design/component-manager.texi
+++ /dev/null
@@ -1,396 +0,0 @@
- at node Component Manager
- at chapter Component Manager
- at cindex Component Manager
-
- at strong{This whole document is completely outdated. Don't read this. All
-function names and every described structure has changed
-completely. Only read this if you want to know how gnucash looked like
-in 1999. This is completely outdated!}
-
-The Component Manager (hereafter referred to as the CM) is a framework
-for managing GUI objects in GnuCash. The CM provides several services.
-
-First, components may request automatic invocation of a 'refresh'
-handler that is called when a component may need to be redrawn. This
-mechanism is tied into the Engine's Event mechanism (@pxref{Events}),
-so that GUI components are notified when relevant Engine entities are
-created, modified, or destroyed.
-
-Components may also provide a 'close' handler so that the component
-may be closed through the CM API.
-
-The CM also provides the ability to search for existing components.
-
-
- at menu
-* Component Manager Introduction::
-* Refresh Mechanism::
-* CM Initialization and Shutdown::
-* Refresh Handlers::
-* Close Handlers::
-* Registering and Unregistering Components::
-* Watching Engine Objects::
-* Controlling Refreshes::
-* Finding Components::
-* Iterating over Components::
- at end menu
-
-
- at node Component Manager Introduction, Refresh Mechanism, Component Manager, Component Manager
- at section Introduction
-
-The GnuCash GUI must manage many different components (registers,
-reconcile windows, reports, graphs, main window, etc.). Functions which
-need to be performed on or with GUI components include:
-
-
- at itemize
-
- at item Refreshing components. When Engine objects (Accounts,
-Transactions, Splits, etc.) are created, modified, or destroyed,
-the GUI components which reference those objects must be refreshed.
-
- at item Searching for existing components. For example, when the
-user chooses to 'Reconcile' an account with an existing reconcile
-dialog, that dialog should be raised to the top in lieu of creating
-a new reconcile dialog.
-
- at item Closing components.
-
- at end itemize
-
-
-In particular, keeping components updated in the face of changes in the
-Engine is a difficult problem. Requirements for handling refreshes
-include:
-
- at itemize
-
- at item The Engine should be able to inform user code when any account
-or transaction is changed (including changing their respective splits).
-This requirement is satisfied by the Engine Events.
-
- at item The refresh mechanism should not have specific knowledge of
-individual windows and other GUI elements. It should be easy to
-add new refreshable elements to the mechanism.
-
- at item Changes should be batchable with respect to refreshes, so that
-a sequence of changes only cause a refresh after the last change
-in a batch. Batching should be nestable, for coding simplicity.
-
- at item For very large batches of changes (loading files) we need to be
-able to turn off the mechanism entirely, perform the changes, and then
-perform a global, forced refresh. This should also be nestable.
-
- at item The Engine should not be managing GUI components.
-
- at item The refresh mechanism should be extendable to a multi-user
-situation in which changes can come from external components.
-
- at item Components should be able to specify which Engine entities
-can cause refreshes. This requirement allows the implementation
-to avoid unnecessary refreshing.
-
- at end itemize
-
-
- at node Refresh Mechanism, CM Initialization and Shutdown, Component Manager Introduction, Component Manager
- at section Refresh Mechanism
- at cindex Refresh Mechanism
-
-The major design decisions of the CM relate to the refresh
-mechanism. The refresh mechanism consists of two parts, the Engine
-component and the GUI component. The Engine component is the
-Event mechanism (@pxref{Events}), while the GUI component is the
-Component Manager, which provide refresh functionality as well
-as other services.
-
-The diagram below illustrated the design of the GnuCash refresh
-mechanism.
-
- at example
- ----------
- | |
- | Engine |
- | |
- ----------
- /|\
- |
- |--- Events (from Engine)
- |
- \|/
- -------------------------
- | |
- | Component Manager |
- | |
- -------------------------
- / /|\ \ GUI Commands
- / | \--- including refresh
- / \|/ \ invocations (from CM)
------------------ -----------------
-| | | |
-| GUI Component | | GUI Component | ...
-| | | |
------------------ -----------------
- at end example
-
-The top-level component is the Engine, which emits Events to the
-Component Manager. In fact, the Engine will send events to any
-registered handler, but in GnuCash, only the CM registers with
-the engine. All other GUI components register with the CM.
-
-The CM invokes the refresh handlers of GUI components based on the
-Engine events received the CM has received as well as information
-provided by the GUI components (such as which specific Engine
-entities the components are 'watching').
-
-
- at node CM Initialization and Shutdown, Refresh Handlers, Refresh Mechanism, Component Manager
- at section Initialization and Shutdown
-
- at deftypefun void gnc_component_manager_init (void)
-Initialize the Component Manager. This should be called
-before using an other CM functions.
- at end deftypefun
-
- at deftypefun void gnc_component_manager_shutdown (void)
-Shutdown the Component Manager. This should be called
-to release Component Manager resources.
- at end deftypefun
-
-
- at node Refresh Handlers, Close Handlers, CM Initialization and Shutdown, Component Manager
- at section Refresh Handlers
- at tindex EventInfo
-
-When a component registers itself with the CM, it may specify two
-different handlers: a refresh handler and a close handler. A refresh
-handler is a function with the following type signature:
-
- at deftp {Data type} GNCComponentRefreshHandler void (*) (GHashTable *@var{changes}, gpointer @var{user_data})
-This is the type signature of a refresh handler. The @var{changes} hash
-describes the Engine events which have occurred since the last refresh.
-It is used to determine whether a refresh is actually needed. It may,
-however, be @code{NULL}, meaning the component must perform a refresh.
-The @code{user_data} pointer is the data pointer supplied when the
-component was registered.
- at end deftp
-
-When a refresh handler is invoked, it should perform the following actions:
-
- at enumerate
-
- at item Check if the component should be closed. When a refresh handler
-is invoked, any and all of the Engine objects which the component was
-referencing may have been destroyed, possibly making the component
-obsolete. For example, a dialog to edit the parameters of a specific
-Account should be automatically closed when the account is deleted. On
-the other hand, a list of all Accounts in a hierarchy should be updated
-when an Account is deleted, but not necessarily closed.
-
-Components must test for the destruction of critical Engine objects
-in two ways.
-
- at enumerate
-
- at item Use the @code{GUID} lookup functions (such as
- at code{xaccAccountLookup}), to determine if the engine object is still
-bound to its @code{GUID}. Of course, this means that components should
-store the @code{GUID}s of critical Engine objects instead of simply
-storing their C pointers.
-
- at item If the first test succeeds and the @var{changes} hash table
-of the refresh handler is non-NULL, the component should use the hash to
-determine of the GNC_EVENT_DESTROY event has occurred for the Engine
-object in question. The @var{changes} hash is a mapping from
- at code{GUID}s to @code{EventInfo} structures. An @code{EventInfo}
-structure has a single member, @code{event_mask}, of type
- at code{GNCEngineEventType}. The @code{event_mask} is a logical or of the
- at code{GNC_EVENT_CREATE}, @code{GNC_EVENT_MODIFY}, and
- at code{GNC_EVENT_DESTROY} event types. Since refreshes may not occur with
-every Engine event, @code{event_mask} may have all three values.
-
-There is a utility function for accessing the @var{changes} hash:
-
- at deftypefun {const EventInfo *} gnc_gui_get_entity_events (GHashTable * @var{changes}, const GUID * @var{entity})
-Return the event info for the entity specified by @var{entity}. If there
-are no events for that entity, @code{NULL} is returned.
- at end deftypefun
-
- at end enumerate
-
-If the @var{changes} hash is NULL, then the first test is sufficient
-to determine whether an object has been destroyed.
-
-If the refresh handler determines the component should be destroyed,
-it should destroy the component and return.
-
- at item Check if the component should be refreshed. If the @var{changes}
-hash is @code{NULL}, then the component must refresh itself. Otherwise,
-it may use the @var{changes} hash to determine whether or not a refresh
-is actually necessary. However, since the component may specify which
-particular Engine objects are relevant (see "Watching Components"
-below), generally a component will simply refresh unconditionally.
-
- at item Refresh the component if necessary. This includes updating the
-GUI as well as internal structures to reflect the new state of Engine
-objects.
-
- at end enumerate
-
-
- at node Close Handlers, Registering and Unregistering Components, Refresh Handlers, Component Manager
- at section Close Handlers
-
-A close handler is a function with the following type signature:
-
- at deftp {Data type} GNCComponentCloseHandler void (*) (gpointer @var{user_data})
-This is the type signature of a close handler. The @code{user_data}
-pointer is the data pointer supplied when the component was registered.
- at end deftp
-
-The invocation of a close handler is a command to the component to close
-itself. The component must close itself -- the handler should not be
-ignored. The component is still responsible for unregistering itself
-with the Component Manager.
-
-
- at node Registering and Unregistering Components, Watching Engine Objects, Close Handlers, Component Manager
- at section Registering and Unregistering Components
-
- at deftypefun gint gnc_register_gui_component (const char * @var{component_class}, GNCComponentRefreshHandler @var{refresh_handler}, GNCComponentCloseHandler @var{close_handler}, gpointer @var{user_data})
-Register a gui component with the Component Manager.
-
-The variable @var{component_class} is a string specifying a class of
-components. Certain CM functions can be performed on all components in a
-class. For that reason, components in the same class should all use the
-same type for @var{user_data}.
-
- at var{refresh_handler} and @var{close_handler} specify the refresh and close
-handlers, respectively. Either or both may be @code{NULL}.
-
-The @var{user_data} is supplied as an argument when the handlers are invoked.
-
-The function returns the id of the newly-registered component, or
- at code{NO_COMPONENT} if there was an error.
- at end deftypefun
-
-After a refresh handler is registered, the component must use the API
-calls under "Watching Engine Objects" below to inform the Component
-Manager which engine entities are being watched, i.e., which engine
-entities may cause the component to need refreshing. When a component is
-first registered, it is not watching anything, and thus will not receive
-refresh events.
-
- at deftypefun void gnc_unregister_gui_component (gint @var{component_id})
-Unregister the component with id @var{component} from the CM.
- at end deftypefun
-
- at deftypefun void gnc_unregister_gui_component_by_data (const char * @var{component_class}, gpointer @var{user_data})
-Unregister all gui components in the class @var{component_class} which have
- at var{user_data} as a user data pointer.
- at end deftypefun
-
-
- at node Watching Engine Objects, Controlling Refreshes, Registering and Unregistering Components, Component Manager
- at section Watching Engine Objects
-
- at deftypefun void gnc_gui_component_watch_entity (gint @var{component_id}, const GUID * @var{entity}, GNCEngineEventType @var{event_mask})
-If @var{event_mask} is non-zero, add the Engine entity specified by
- at var{entity} to the list of entities being watched by the component with
-id @var{component_id}. Only the events specified by @var{events} are
-watched. If @var{event_mask} is 0, the call turns off watching for the
-entity.
- at end deftypefun
-
- at deftypefun void gnc_gui_component_watch_entity_type (gint @var{component_id}, GNCIdType @var{entity_type}, GNCEngineEventType @var{event_mask})
-if @var{event_mask}, turn on watching for all entities of @var{entity_type}.
-Only events specified by @var{event_mask} are watched. If @var{event_mask}
-is 0, turns off watching for the entity type.
- at end deftypefun
-
- at deftypefun void gnc_gui_component_clear_watches (gint @var{component_id})
-Clear all watches for the component with id @var{component_id}.
- at end deftypefun
-
-
- at node Controlling Refreshes, Finding Components, Watching Engine Objects, Component Manager
- at section Controlling Refreshes
-
- at deftypefun void gnc_suspend_gui_refresh (void)
-Suspend the invocation of refresh handlers by the Component Manager.
-This routine may be called multiple times. Each call increases the
-suspend counter which starts at zero. When refreshes are not suspended,
-any engine event causes a refresh cycle in which the refresh handler for
-every component watching for that event is invoked.
- at end deftypefun
-
- at deftypefun void gnc_resume_gui_refresh (void)
-Resume the invocation of refresh handlers by the Component Manager.
-Each call reduces the suspend counter by one. When the counter reaches
-zero, all events which have occurred since the last refresh are collected
-and passed to refresh handlers via the @var{changes} argument. Refresh
-handlers will still be excluded based on their watches.
- at end deftypefun
-
- at deftypefun void gnc_gui_refresh_all (void)
-Force all components to refresh, i.e., invoke all refresh handlers
-with a @code{NULL} value for @var{changes}.
-
-This routine may only be invoked when the suspend counter is zero. It
-should never be mixed with the suspend/resume refresh routines.
- at end deftypefun
-
- at deftypefun gboolean gnc_gui_refresh_suspended (void)
-Returns TRUE if GUI refreshing is currently suspended.
- at end deftypefun
-
-
- at node Finding Components, Iterating over Components, Controlling Refreshes, Component Manager
- at section Finding Components
-
-The Component Manager API provides two functions that allow components
-to be searched for. Each function uses a find handler to perform the
-actual search work. A find handler is a function with the following
-signature:
-
- at deftp {Data type} GNCComponentFindHandler gboolean (*) (gpointer @var{find_data}, gpointer @var{user_data})
-A find handler is invoked with the @var{find_data} specified in the search
-API call, and the @var{user_data} of a particular component. The handler
-should return TRUE if the component matches the search criteria and FALSE
-otherwise.
- at end deftp
-
- at deftypefun {GList *} gnc_find_gui_components (const char * @var{component_class}, GNCComponentFindHandler @var{find_handler}, gpointer @var{find_data})
-Search for all components in class @var{component_class} using @var{find_handler}. Return a @code{GList} of the user data pointers of matching components.
- at end deftypefun
-
- at deftypefun gpointer gnc_find_first_gui_component (const char * @var{component_class}, GNCComponentFindHandler @var{find_handler}, gpointer @var{find_data})
-Like @code{gnc_find_gui_components} above, but return the user data pointer
-of the first matching component, or @code{NULL} if there are no matching
-components.
- at end deftypefun
-
-
- at node Iterating over Components, , Finding Components, Component Manager
- at section Iterating over Components
-
-The Component Manager API provides a function for iterating over all
-components in a class as well as all registered components regardless
-of class.
-
-In either case, a generic component handler is invoked for each
-component. The handler has the following signature:
-
- at deftp {Data type} GNCComponentHandler void (*) (const char * @var{class}, gint @var{component_id}, gpointer @var{iter_data})
-The component handler is invoked with the @var{class},
- at var{component_id} of a particular component, as well as the
- at var{iter_data} supplied in the iteration API call.
- at end deftp
-
- at deftypefun void gnc_forall_gui_components (const char * @var{component_class}, GNCComponentHandler @var{handler}, gpointer @var{iter_data})
-Apply @var{handler} to every component in @var{component_class}. If
- at var{component_class} is @code{NULL}, then iteration is performed over
-every registered component. @var{iter_data} is supplied to @var{handler}
-as the third argument.
- at end deftypefun
diff --git a/libgnucash/doc/design/concept-index.texi b/libgnucash/doc/design/concept-index.texi
deleted file mode 100644
index fcf9204c62..0000000000
--- a/libgnucash/doc/design/concept-index.texi
+++ /dev/null
@@ -1,4 +0,0 @@
- at node Concept Index, , Data Type Index, Top
- at unnumbered Concept Index
-
- at printindex cp
diff --git a/libgnucash/doc/design/engine.texi b/libgnucash/doc/design/engine.texi
deleted file mode 100644
index 9cbc410f8e..0000000000
--- a/libgnucash/doc/design/engine.texi
+++ /dev/null
@@ -1,2826 +0,0 @@
- at node Engine, Component Manager, Top Level, Top
- at chapter Engine
- at cindex The Engine
-
- at strong{This whole document is completely outdated. Don't read this. All
-function names and every described structure has changed
-completely. Only read this if you want to know how gnucash looked like
-in 1999. This is completely outdated!}
-
-The Engine provides an interface to a financial engine with three basic
-financial entities: Accounts, Transactions (known as Journal Entries in
-accounting practice), and Splits (known as Ledger Entries). These three
-entities are the central data structures of the GnuCash financial data
-model.
-
-In addition, the Engine provides the abstraction of Account Groups
-(collections of related accounts) and GNCBooks. A GNCBook abstracts both
-a set of related GnuCash data (financial entities plus additional
-information such as budgets, per-file preferences, etc.) plus a
-file-editing session allowing transparent support for locking and
-implementation with other backends such as SQL.
-
-The Engine code contains no GUI code whatsoever and is designed to
-be created as a shared library for use by other programs.
-
- at menu
-* Engine Introduction::
-* Using and Extending the Engine API::
-* Globally Unique Identifiers::
-* Numeric Library::
-* Key-Value Pair Frames::
-* Events::
-* Commodities::
-* Commodity Tables::
-* Prices::
-* Price Databases::
-* Splits::
-* Transactions::
-* Accounts::
-* Account Groups::
-* GNCBooks::
-* Scrub::
- at end menu
-
-
- at node Engine Introduction, Using and Extending the Engine API, Engine, Engine
- at section Introduction
-
-Splits (@pxref{Splits}), or "Ledger Entries" are the fundamental
-accounting units. Each Split consists of an amount (number of dollar
-bills, number of shares, etc.), the value of that amount expressed in
-a (possibly) different currency than the amount, a Memo, a pointer to
-the parent Transaction, a pointer to the debited Account, a reconciled
-flag and timestamp, an "Action" field, and a key-value frame which can
-store arbitrary data (@pxref{Key-Value Pair Frames}).
-
-Transactions (@pxref{Transactions}) embody the notion of "double entry"
-accounting. A Transaction consists of a date, a description, an ID number, a
-list of one or more Splits, and a key-value frame. The transaction
-also specifies the currency with which all of the splits will be
-valued. When double-entry rules are enforced, the total value of
-the splits are zero. If there are only two splits,
-then the value of one must be positive, the other negative: this denotes
-that one account is debited, and another is credited by an equal
-amount. By forcing the value of the splits to always 'add up' to
-zero, we can guarantee that the balances of the accounts are always
-correctly balanced.
-
-The engine does not enforce double-entry accounting, but provides an API
-to enable user-code to find unbalanced transactions and 'repair' them so
-that they are in balance. @xref{Scrub}.
-
-Note the sum of the values of Splits in a Transaction is always computed
-with respect to a currency; thus splits can be balanced even when they
-are in different currencies, as long as they share a common currency.
-This feature allows currency-trading accounts to be established.
-
-Every Split must point to its parent Transaction, and that Transaction
-must in turn include that Split in the Transaction's list of Splits. A
-Split can belong to at most one Transaction. These relationships are
-enforced by the engine. The engine user cannot accidentally destroy
-this relationship as long as they stick to using the API and never
-access internal structures directly.
-
-Splits are grouped into Accounts (@pxref{Accounts}) which are also known
-as "Ledgers" in accounting practice. Each Account consists of a list of
-Splits that debit that Account. To ensure consistency, if a Split points
-to an Account, then the Account must point to the Split, and vice-versa.
-A Split can belong to at most one Account. Besides merely containing a
-list of Splits, the Account structure also give the Account a name, a
-code number, description and notes fields, a key-value frame, a pointer
-to the commodity that is used for all splits in this account. The
-commodity can be the name of anything traded and tradable: a stock
-(e.g. "IBM", "McDonald's"), a currency (e.g. "USD", "GBP"), or
-anything added to the commodity table.
-
-Accounts can be arranged in a hierarchical tree. The nodes of the tree
-are called "Account Groups" (@pxref{Account Groups}). By accounting
-convention, the value of an Account is equal to the value of all of its
-Splits plus the value of all of its sub-Accounts.
-
-
- at node Using and Extending the Engine API, Globally Unique Identifiers, Engine Introduction, Engine
- at section Using and Extending the Engine API
-
-Engine API calls are named using a specific convention. For example,
-the function to access the Memo field of a Split is
- at code{xaccSplitGetMemo}. The prefix @code{xacc} comes
-first at footnote{The @code{xacc} prefix is a historical artifact. GnuCash
-was derived from X-Accountant by Robin Clark.}, followed by the name of
-the entity for which the API call applies (@code{Split}), followed by
-the action performed by the call (@code{Get}), followed by the name of
-the field being accessed (@code{Memo}). Future API calls should conform
-to this naming convention.
-
-The formal arguments to Engine API calls always begin with the entity to
-which the call applies. Thus, the arguments to @code{xaccSplitSetMemo}
-are the @code{Split} pointer followed by the pointer to a memo
-string. Future API calls should also conform to this convention.
-
-Engine API calls should be implemented to behave as gracefully as
-possible with unexpected input. Specifically, public API calls should
-gracefully handle @code{NULL} pointer arguments. User code should be
-able to handle @code{NULL} return values from Engine calls as well.
-
-
- at node Globally Unique Identifiers, Numeric Library, Using and Extending the Engine API, Engine
- at section Globally Unique Identifiers
- at cindex Globally Unique Identifier
- at tindex GUID
-
-It is common for Engine structures to reference other Engine structures.
-For example, an Account must reference its Splits, its parent Account
-Group, and its child Account Group. Furthermore, other GnuCash modules
-may need to reference Engine structures. For example, a GUI
-implementation may wish to save a list of Accounts which the user has
-open when the application exits in order to restore that same state upon
-the next invocation.
-
-One way to uniquely identify an Engine structure, at least while the
-program is running, is using the C pointer which points to the
-structure. C pointers have the advantage of speed, but also have some
-disadvantages:
-
- at itemize
-
- at item
-Pointers cannot be used in data files and are not persistent across
-different program invocations.
-
- at item
-When an entity is destroyed, every other structure which references that
-entity through a direct pointer must be immediately updated to prevent
-illegal accesses.
-
- at end itemize
-
-The @dfn{GUID} (Globally Unique Identifier) provides a way to reference
-Engine structures that is more flexible than C pointers. Each Engine
-structure has an associated GUID which can be used to reference that
-structure. Engine GUIDs have the following features:
-
- at itemize
-
- at item
-The GUID is permanent, i.e., it persists between invocations of GnuCash.
-
- at item
-The GUID is guaranteed to be unique with the set of all Splits,
-Transactions, and Accounts in the hierarchy of which the structure
-is a member.
-
- at item
-With very high probability, the GUID is unique among all GUIDs
-created by any invocation of GnuCash, all over the world.
-
- at item
-GUIDs can be efficiently encoded in a string representation.
-
- at end itemize
-
-
- at menu
-* When to use GUIDs::
-* GUID Types::
-* How to use GUIDs::
-* GUIDs and GnuCash Entities::
-* The GUID Generator::
- at end menu
-
- at node When to use GUIDs, GUID Types, Globally Unique Identifiers, Globally Unique Identifiers
- at subsection When to use GUIDs
- at cindex When to use GUIDs
-
-Although GUIDs are very flexible, the engine structures like Accounts
-will probably continue to use C pointers for the foreseeable future,
-since they are much faster (and in certain respects more convenient)
-than using GUIDs. In general, however, it is much safer to use GUIDs.
-In particular, you should consider using GUIDs if any of the following
-is true:
-
- at itemize
-
- at item
-You need to save a reference to an engine structure in a file.
-
- at item
-You need to save a reference to an engine structure that could
-be deleted in between accesses to the saved reference.
-
- at end itemize
-
-
- at node GUID Types, How to use GUIDs, When to use GUIDs, Globally Unique Identifiers
- at subsection GUID Types
- at tindex GNCIdType
-
-The GUIDs in GnuCash are typed using the enum @code{GNCIdType}.
-Possible values and their meanings for GUID types are:
-
- at table @code
-
- at item GNC_ID_NONE
-The GUID does not currently refer to a GnuCash entity, though it
-could refer to one in the future.
-
- at item GNC_ID_NULL
-The GUID does not, and never will, refer to a GnuCash entity.
-
- at item GNC_ID_ACCOUNT
-The GUID refers to an Account (@pxref{Accounts}).
-
- at item GNC_ID_TRANS
-The GUID refers to a Transaction (@pxref{Transactions}).
-
- at item GNC_ID_SPLIT
-The GUID refers to a Split (@pxref{Splits}).
-
- at end table
-
- at deftypefun GNCIdType xaccGUIDType (const GUID * @var{guid})
-Return the type associated with @var{guid}.
- at end deftypefun
-
- at deftypefun {const GUID *} xaccGUIDNull (void)
-Return a GUID which is guaranteed to always have type @code{GNC_ID_NULL}.
- at end deftypefun
-
-
- at node How to use GUIDs, GUIDs and GnuCash Entities, GUID Types, Globally Unique Identifiers
- at subsection How to use GUIDs
-
-The Engine API functions which access the GUID for a specific entity
-return a pointer to the GUID. NOTE: Do not store the pointer
-itself! Instead, store a copy of the GUID. Storing the pointer itself
-would present some of the same problems as using the account pointer
-directly. Example:
-
- at example
-@{
- GUID saved_guid;
- Account *account;
-
- account = < something to get an Account pointer >
-
- saved_guid = *xaccAccountGetGUID(account);
-
- ...
-
- account = xaccAccountLookup(&saved_guid);
-
- ...
-@}
- at end example
-
-You can compare two GUIDs with the following functions.
-
- at deftypefun gboolean guid_equal (const GUID * @var{guid_1}, const GUID * @var{guid_2})
-Compare two guids and return TRUE if they are both non-NULL and equal.
- at end deftypefun
-
- at deftypefun gint guid_compare (const GUID * @var{g1}, const GUID * @var{g2})
-Return the @code{memcmp} of the two GUID's.
- at end deftypefun
-
-
-You can encode and decode GUIDs and their string representations using the
-next two functions.
-
- at deftypefun {gchar *} guid_to_string (const GUID * @var{guid})
-Return a null-terminated string encoding of @var{guid}. String encodings
-of identifiers are hex numbers printed only with the characters @code{0}
-through @code{9} and @code{a} through @code{f}. The encoding will
-always be @code{GUID_ENCODING_LENGTH} characters long. The returned
-string must be freed when no longer needed using g_free.
- at end deftypefun
-
- at deftypefun {char *} guid_to_string_buff (const GUID * @var{guid}, char * @var{buff})
-This routine does the same work as @code{guid_to_string}, except that the
-string is written into the memory pointed at by @var{buff}. The
-buffer must be at least GUID_ENCODING_LENGTH+1 characters long.
-This routine is handy for avoiding a malloc/free cycle.
-It returns a pointer to the @emph{end} of what was written.
-(i.e. it can be used like @code{stpcpy} during string concatenation)
- at end deftypefun
-
- at deftypefun gboolean string_to_guid (const char * @var{string}, GUID * @var{guid})
-Given a string, decode an id into @var{guid} if @var{guid} is
-non-NULL. The function returns TRUE if the string was a valid 32
-character hexadecimal number. This function accepts both upper and lower
-case hex digits. If the return value is FALSE, the effect on @var{guid}
-is undefined.
- at end deftypefun
-
-
-You can allocate and deallocate space for GUIDs using standard
-memory routines. However, if your code is allocating and deallocating
-lots of GUID objects, then the next two functions should be used.
-
- at deftypefun {GUID *} xaccGUIDMalloc (void)
-Return newly allocated memory for a GUID object. The memory must
-be freed with @code{xaccGUIDFree}. In general, this function is
-faster than using the standard libc allocators.
- at end deftypefun
-
- at deftypefun void xaccGUIDFree (GUID * @var{guid})
-Free the space for a GUID that was allocated with @code{xaccGUIDMalloc}.
- at end deftypefun
-
-
-You can use the following two functions to aid in using GUIDS in hash
-tables.
-
- at deftypefun guint guid_hash_to_guint (gconstpointer @var{ptr})
-Return a hash value suitable for use with a @code{GHashTable}.
- at var{ptr} must point to a GUID.
- at end deftypefun
-
- at deftypefun {GHashTable *} guid_hash_table_new (void)
-Return a new @code{GHashTable} which uses GUIDs as keys.
- at end deftypefun
-
-
- at node GUIDs and GnuCash Entities, The GUID Generator, How to use GUIDs, Globally Unique Identifiers
- at subsection GUIDs and GnuCash Entities
-
-This section documents a low-level API for associating entities with
-GUIDs. User code and general engine code should not use this API;
-instead use the API documented in the sections for the specific GnuCash
-entities such as Accounts and Transactions.
-
- at deftypefun void xaccGUIDNew (GUID * @var{guid})
-Generate a new guid. This function is guaranteed to return a guid that
-is unique within the scope of all GnuCash entities being managed by the
-the current invocation of GnuCash. GnuCash routines should always use
-this function and not @code{guid_replace}!
- at end deftypefun
-
- at deftypefun {void *} xaccLookupEntity (const GUID * @var{guid}, GNCIdType @var{entity_type})
-Lookup an entity given an id and a type. If there is no entity
-associated with the id, or if it has a different type, NULL is returned.
- at end deftypefun
-
- at deftypefun void xaccStoreEntity (void * @var{entity}, const GUID * @var{guid}, GNCIdType entity_type)
-Store the given entity under the given id with the given type.
- at end deftypefun
-
- at deftypefun void xaccRemoveEntity (const GUID * @var{guid})
-Remove any existing association between an entity and the given id. The
-entity is not changed in any way.
- at end deftypefun
-
-
- at node The GUID Generator, , GUIDs and GnuCash Entities, Globally Unique Identifiers
- at subsection The GUID Generator
- at cindex The GUID Generator
-
-GUIDs are created by the GUID generator. The API for this generator is
-low-level and should not be used by user-code.
-
- at deftypefun void guid_replace (GUID * @var{guid})
-Create a new GUID and store it in @var{guid}. This is a low-level function!
-GnuCash code should use @code{xaccGUIDNew}.
- at end deftypefun
-
-
- at node Numeric Library, Key-Value Pair Frames, Globally Unique Identifiers, Engine
- at section Numeric Library
- at cindex Numeric Library
- at tindex gnc_numeric
-
-=============== The documentation below for gnc_numeric is obsolete
- and has been superseded by the gnc_numeric docs in the header file.
-=========================================
-
-Financial quantities in GnuCash (Split quantities and values) are stored
-as exact quantities measured in the smallest denominational unit of the
-appropriate currency. For example, 100.50 US Dollars would be stored as
-(10050 / 100) US Dollars. GnuCash uses the @code{gnc_numeric} datatype
-to store financial quantities.
-
-The @code{gnc_numeric} API provides data types and functions for
-manipulating exact numeric quantities. While the @code{gnc_numeric}
-library was developed to represent and operate on exact financial
-quantities in GnuCash, the library is also (hopefully) suitable for use
-in any application where exact numeric representation for rational
-numbers is needed.
-
-A @code{gnc_numeric} value represents a number in rational form, with a
-64-bit @code{long long} integer as numerator and denominator. If more
-precision, a higher-precision representation of irrational numbers, or a
-wider dynamic range is needed, a floating point format may be
-appropriate. There are reasonable rational approximations to common
-irrational constants (@pxref{Numeric Example}), but the transcendental
-functions have not been implemented for @code{gnc_numeric} objects.
-
- at menu
-* Standard Numeric Arguments::
-* Creating Numeric Objects::
-* Basic Arithmetic Operations::
-* Numeric Comparisons and Predicates::
-* Numeric Denominator Conversion::
-* Numeric Floating Point Conversion::
-* Numeric String Conversion::
-* Numeric Error Handling ::
-* Numeric Example::
- at end menu
-
- at node Standard Numeric Arguments, Creating Numeric Objects, Numeric Library, Numeric Library
- at subsection Standard Numeric Arguments
- at cindex Standard Numeric Arguments
-
-=============== The documentation below for gnc_numeric is obsolete
- and has been superseded by the gnc_numeric docs in the header file.
-=========================================
-
-It is useful to specify a denominator in cases where it is known that
-the output value is of constrained precision. For example, monetary
-transactions must be executed in an integer number of the "smallest
-currency unit" of the transaction. In US Dollars, the smallest currency
-unit is the cent, and all monetary transactions must be done in units of
-cents. Therefore, any fractional cents in a computed price must be
-rounded away.
-
-Most of the @code{gnc_numeric} arithmetic functions take two arguments
-in addition to their numeric args: @var{denom}, which is the denominator
-to use in the output @code{gnc_numeric object}, and @var{how}, which
-describes how the arithmetic result is to be converted to that
-denominator. This combination of output denominator and rounding policy
-allows the results of financial and other exact computations to be
-properly rounded to the appropriate units.
-
-Valid values for @var{denom} are:
-
- at table @code
-
- at item n (positive int)
-Use the number @code{n} as the denominator of the output value.
-
- at item GNC_DENOM_RECIPROCAL (n)
-Use the value @code{1/n} as the denominator of the output value.
-
- at item GNC_DENOM_AUTO
-Compute an appropriate denominator automatically. Flags in the @var{how}
-argument will specify how to compute the denominator.
-
- at end table
-
-
-Valid values for @var{how} are bitwise combinations of zero or one
-"rounding instructions" with zero or one "denominator types".
-
-Rounding instructions control how fractional parts in the specified
-denominator affect the result. For example, if a computed result is
-"3/4" but the specified denominator for the return value is 2, should
-the return value be "1/2" or "2/2"?
-
-Possible rounding instructions are:
-
- at table @code
-
- at item GNC_RND_FLOOR
-Round toward -infinity
-
- at item GNC_RND_CEIL
-Round toward +infinity
-
- at item GNC_RND_TRUNC
-Truncate fractions (round toward zero)
-
- at item GNC_RND_PROMOTE
-Promote fractions (round away from zero)
-
- at item GNC_RND_ROUND
-Use unbiased ("banker's") rounding. This rounds to the nearest integer,
-and to the nearest even integer when there are two equidistant nearest
-integers. This is generally the one you should use for financial
-quantities.
-
- at item GNC_RND_ROUND_HALF_UP
-Round to the nearest integer, rounding away from zero when there are two
-equidistant nearest integers.
-
- at item GNC_RND_ROUND_HALF_DOWN
-Round to the nearest integer, rounding toward zero when there are two
-equidistant nearest integers.
-
- at item GNC_RND_NEVER
-Never round at all, and signal an error if there is a fractional result
-in a computation.
-
- at end table
-
-
-The denominator type specifies how to compute a denominator if
- at code{GNC_DENOM_AUTO} is specified as the @var{denom}. Valid denominator
-types are:
-
- at table @code
-
- at item GNC_DENOM_EXACT
-Use any denominator which gives an exactly correct ratio of numerator to
-denominator. Use EXACT when you do not wish to lose any information in
-the result but also do not want to spend any time finding the "best"
-denominator.
-
- at item GNC_DENOM_REDUCE
-Reduce the result value by common factor elimination, using the smallest
-possible value for the denominator that keeps the correct ratio. The
-numerator and denominator of the result are relatively prime. This can
-be computationally expensive for large fractions.
-
- at item GNC_DENOM_LCD
-Find the least common multiple of the arguments' denominators and use
-that as the denominator of the result.
-
- at item GNC_DENOM_FIXED
-All arguments are required to have the same denominator, that
-denominator is to be used in the output, and an error is to be signaled
-if any argument has a different denominator.
-
- at item GNC_DENOM_SIGFIG
-Round to the number of significant figures given in the rounding
-instructions by the GNC_DENOM_SIGFIGS () macro.
-
- at item GNC_DENOM_SIGFIGS (n)
-Use a value for the denominator that will keep at least @code{n}
-significant figures in the result.
-
- at end table
-
-
-To use traditional rational-number operational semantics (all results
-are exact and are reduced to relatively-prime fractions) pass the
-argument @code{GNC_DENOM_AUTO} as @var{denom} and @code{GNC_DENOM_REDUCE
-| GNC_RND_NEVER} as @var{how}.
-
-To enforce strict financial semantics (such that all operands must have
-the same denominator as each other and as the result), use
- at var{GNC_DENOM_AUTO} as @var{denom} and @code{GNC_DENOM_FIXED |
-GNC_RND_NEVER} as @var{how}.
-
-
- at node Creating Numeric Objects, Basic Arithmetic Operations, Standard Numeric Arguments, Numeric Library
-
-=============== The documentation below for gnc_numeric is obsolete
- and has been superseded by the gnc_numeric docs in the header file.
-=========================================
-
- at subsection Creating Numeric Objects
- at cindex Creating Numeric Objects
-
- at deftypefun gnc_numeric gnc_numeric_create (int @var{num}, int @var{denom})
-Create a @code{gnc_numeric} object with a value of "@var{num} / @var{denom}".
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_zero ()
-Create a @code{gnc_numeric} object with a value of 0.
- at end deftypefun
-
-
- at node Basic Arithmetic Operations, Numeric Comparisons and Predicates, Creating Numeric Objects, Numeric Library
- at subsection Basic Arithmetic Operations
- at cindex Basic Arithmetic Operations
-
-See @ref{Standard Numeric Arguments} for a description of the @var{denom}
-and @var{how} arguments to each arithmetic function.
-
- at deftypefun gnc_numeric gnc_numeric_add (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
-Return the sum of @var{a} and @var{b}.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_sub (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
-Return "@var{a} - @var{b}".
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_mul (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
-Return the product of @var{a} and @var{b}.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_div (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
-Return "@var{a} / @var{b}".
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_neg (gnc_numeric @var{a})
-Return "- at var{a}".
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_abs (gnc_numeric @var{a})
-Return the absolute value of @var{a}.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_add_fixed (gnc_numeric @var{a}, gnc_numeric @var{b})
-Equivalent to @code{gnc_numeric_add} on @var{a} and @var{b} with
- at code{GNC_DENOM_AUTO} for @var{denom} and @code{GNC_DENOM_FIXED |
-GNC_RND_NEVER} for @var{how}.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_sub_fixed (gnc_numeric @var{a}, gnc_numeric @var{b})
-Equivalent to @code{gnc_numeric_sub} on @var{a} and @var{b} with
- at code{GNC_DENOM_AUTO} for @var{denom} and @code{GNC_DENOM_FIXED |
-GNC_RND_NEVER} for @var{how}.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_add_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
-The same as @code{gnc_numeric_add}, but uses @var{error} for accumulating
-conversion roundoff error.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_sub_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
-The same as @code{gnc_numeric_sub}, but uses @var{error} for accumulating
-conversion roundoff error.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_mul_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
-The same as @code{gnc_numeric_mul}, but uses @var{error} for accumulating
-conversion roundoff error.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_div_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
-The same as @code{gnc_numeric_div}, but uses @var{error} for accumulating
-conversion roundoff error.
- at end deftypefun
-
-
- at node Numeric Comparisons and Predicates, Numeric Denominator Conversion, Basic Arithmetic Operations, Numeric Library
- at subsection Numeric Comparisons and Predicates
- at cindex Numeric Comparisons and Predicates
-
- at deftypefun int gnc_numeric_zero_p (gnc_numeric @var{a})
-Returns 1 if @code{@var{a} == 0}, otherwise returns 0.
- at end deftypefun
-
- at deftypefun int gnc_numeric_positive_p (gnc_numeric @var{a})
-Returns 1 if @code{@var{a} > 0}, otherwise returns 0.
- at end deftypefun
-
- at deftypefun int gnc_numeric_negative_p (gnc_numeric @var{a})
-Returns 1 if @code{@var{a} < 0}, otherwise returns 0.
- at end deftypefun
-
- at deftypefun int gnc_numeric_compare (gnc_numeric @var{a}, gnc_numeric @var{b})
-Returns +1 if @code{@var{a} > @var{b}}, -1 if @code{@var{b} > @var{a}}, 0 if @code{@var{a} == @var{b}}.
- at end deftypefun
-
- at deftypefun int gnc_numeric_eq (gnc_numeric @var{a}, gnc_numeric @var{b})
-Returns 1 if @code{numerator(@var{a}) == numerator(@var{b})} and
- at code{denominator(@var{a}) == denominator(@var{b})}, otherwise returns 0.
- at end deftypefun
-
- at deftypefun int gnc_numeric_equal (gnc_numeric @var{a}, gnc_numeric @var{b})
-Returns 1 if the fraction represented by @var{a} is equal to the fraction
-represented by @var{b}, otherwise returns 0.
- at end deftypefun
-
- at deftypefun int gnc_numeric_same (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
-Convert both @var{a} and @var{b} to @var{denom} (@pxref{Standard Numeric
-Arguments} and compare numerators of the result.
-
- at example
- For example, if @code{@var{a} == 7/16} and @code{@var{b} == 3/4},
- @code{gnc_numeric_same(@var{a}, @var{b}, 2, GNC_RND_TRUNC) == 1}
- because both 7/16 and 3/4 round to 1/2 under truncation. However,
- @code{gnc_numeric_same(@var{a}, @var{b}, 2, GNC_RND_ROUND) == 0}
- because 7/16 rounds to 1/2 under unbiased rounding but 3/4 rounds
- to 2/2.
- at end example
- at end deftypefun
-
-
- at node Numeric Denominator Conversion, Numeric Floating Point Conversion, Numeric Comparisons and Predicates, Numeric Library
-=============== The documentation below for gnc_numeric is obsolete
- and has been superseded by the gnc_numeric docs in the header file.
-=========================================
-
- at subsection Numeric Denominator Conversion
- at cindex Numeric Denominator Conversion
-
- at deftypefun gnc_numeric gnc_numeric_convert (gnc_numeric @var{in}, gint64 @var{denom}, gint @var{how})
-Convert @var{in} to the specified denominator under standard arguments
- at var{denom} and @var{how}. @xref{Standard Numeric Arguments}.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_convert_with_error (gnc_numeric @var{in}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
-Same as @code{gnc_numeric_convert}, but return a remainder value for
-accumulating conversion error.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_reduce (gnc_numeric @var{in})
-Return @var{in} reduced by GCF reduction.
- at end deftypefun
-
-
- at node Numeric Floating Point Conversion, Numeric String Conversion, Numeric Denominator Conversion, Numeric Library
- at subsection Numeric Floating Point Conversion
- at cindex Numeric Floating Point Conversion
-
- at deftypefun gnc_numeric double_to_gnc_numeric (double @var{arg}, gint64 @var{denom}, gint @var{how})
-Convert a floating-point number to a @code{gnc_numeric}. Both @var{denom}
-and @var{how} are used as in arithmetic, but @code{GNC_DENOM_AUTO} is
-not recognized.
- at end deftypefun
-
- at deftypefun double gnc_numeric_to_double (gnc_numeric @var{arg})
-Convert @var{arg} to a @code{double} value.
- at end deftypefun
-
-
- at node Numeric String Conversion, Numeric Error Handling , Numeric Floating Point Conversion, Numeric Library
- at subsection Numeric String Conversion
- at cindex Numeric String Conversion
-
- at deftypefun {gchar *} gnc_numeric_to_string (gnc_numeric @var{n})
-Return a string representation of @var{n}. The string must be
-freed with @code{g_free}.
- at end deftypefun
-
- at deftypefun {const gchar *} string_to_gnc_numeric (const {gchar *} @var{str}, {gnc_numeric *} @var{n})
-Read a @code{gnc_numeric} from @var{str}, skipping any leading
-whitespace, and returning a pointer to just past the last byte
-read. Return NULL on error.
- at end deftypefun
-
-
- at node Numeric Error Handling , Numeric Example, Numeric String Conversion, Numeric Library
- at subsection Numeric Error Handling
- at cindex Numeric Error Handling
-
- at deftypefun int gnc_numeric_check (gnc_numeric @var{num})
-Check @var{num} for the possibility that it is an error signal rather
-than a proper value. Possible return codes are:
-
- at table @code
-
- at item GNC_ERROR_OK
-No error condition
-
- at item GNC_ERROR_ARG
-An improper argument was passed to a function
-
- at item GNC_ERROR_OVERFLOW
-An overflow occurred while calculating a result
-
- at item GNC_ERROR_DENOM_DIFF
- at code{GNC_DENOM_FIXED} was specified, but argument denominators differed.
-
- at item GNC_ERROR_REMAINDER
- at code{GNC_RND_NEVER} was specified, but the result could not be
-converted to the desired denominator without a remainder.
-
- at end table
-
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_error (int error_code)
-Create a @code{gnc_numeric} object that signals the error condition
-noted by @var{error_code} rather than a number.
- at end deftypefun
-
-
- at node Numeric Example, , Numeric Error Handling , Numeric Library
- at subsection Numeric Example
- at cindex Numeric Example
-
-=============== The documentation below for gnc_numeric is obsolete
- and has been superseded by the gnc_numeric docs in the header file.
-=========================================
-
-The following program finds the best @code{gnc_numeric} approximation to
-the @file{math.h} constant @code{M_PI} given a maximum denominator. For
-large denominators, the @code{gnc_numeric} approximation is accurate to
-more decimal places than will generally be needed, but in some cases
-this may not be good enough. For example,
-
- at example
- M_PI = 3.14159265358979323846
- 245850922 / 78256779 = 3.14159265358979311599 (16 sig figs)
- 3126535 / 995207 = 3.14159265358865047446 (12 sig figs)
- 355 / 113 = 3.14159292035398252096 (7 sig figs)
- at end example
-
- at example
-#include <glib.h>
-#include "gnc-numeric.h"
-#include <math.h>
-
-int
-main(int argc, char ** argv)
-@{
- gnc_numeric approx, best;
- double err, best_err=1.0;
- double m_pi = M_PI;
- gint64 denom;
- gint64 max;
-
- sscanf(argv[1], "%Ld", &max);
-
- for (denom = 1; denom < max; denom++)
- @{
- approx = double_to_gnc_numeric (m_pi, denom, GNC_RND_ROUND);
- err = m_pi - gnc_numeric_to_double (approx);
- if (fabs (err) < fabs (best_err))
- @{
- best = approx;
- best_err = err;
- printf ("%Ld / %Ld = %.30f\n", gnc_numeric_num (best),
- gnc_numeric_denom (best), gnc_numeric_to_double (best));
- @}
- @}
-@}
- at end example
-
-
- at node Key-Value Pair Frames, Events, Numeric Library, Engine
- at section Key-Value Pair Frames
- at cindex Key-Value Pairs
-
-The number and types of data items which are associated with the
-financial abstractions (Accounts, Transactions, and Splits) can vary
-widely. For example, an Account which represents a user's checking
-account might need to store the bank name, a telephone number, and a
-username for online banking purposes. Another Account representing the
-user's ownership of a stock might need to store information about
-retrieving price quotes online such as the ticker symbol and the
-exchange.
-
-To meet this need for varying data storage, the GnuCash accounting
-entities use Key-Value Pair Frames (hereafter referred to as the
-datatype @code{kvp_frame}). A @code{kvp_frame} is a set of associations
-between character strings (keys) and @code{KvpValue} structures. A
- at code{KvpValue} is a union with possible types enumerated in the
- at code{kvp_value_t} enum which indicates the type of data stored in a
- at code{KvpValue} object.
-
- at menu
-* Key-Value Policy::
-* kvp_frame::
-* KvpValue::
-* kvp_list::
- at end menu
-
-
- at node Key-Value Policy, kvp_frame, Key-Value Pair Frames, Key-Value Pair Frames
- at subsection Key-Value Policy
- at cindex Key-Value Policy
-
-This section defines the policy that programmers should follow
-when using key-value pairs to store information. Because of the
-large amount of information which can potentially be stored using
-this mechanism, it is important to follow these guidelines so
-that order will be maintained.
-
-The following rules should be followed for using key-value pairs:
-
- at itemize
-
- at item
-The document @file{src/engine/kvp_doc.txt} should be used to document the
-use of keys and values. Please consult this document before planning any
-use of new keys.
-
- at item
-Key strings should be in all lower case with the '-' character
-separating words. If possible, use only alphanumeric characters and
-'-'. Example: @code{bank-info}. Because the '/' character is useful for
-describing keys in sub-frames (@code{bank-info/routing-number}), do not
-use the '/' character in key names.
-
- at item
-Favor longer, descriptive key strings over short ones. Example:
- at code{online-banking-info} is better than @code{onln-bnk}.
-
- at item
-Make use of the fact that frames can be stored in frames. If a group
-of keys are used for a related purpose, consider storing them together
-in a sub-frame.
-
- at item
-Values should generally not be accessed directly through keys, but
-should rather be accessed through specific API calls. The API calls
-do not necessarily need to part a part of the Engine API. For example,
-the GUI would probably define keys that the Engine does not need to
-know about.
-
- at item
-The same key should not be used for different engine structures (Accounts,
-Transactions, Splits), unless the key's value has the same type and the
-same basic purpose.
-
- at end itemize
-
-
- at node kvp_frame, KvpValue, Key-Value Policy, Key-Value Pair Frames
- at subsection kvp_frame
- at tindex kvp_frame
-
-A @code{kvp_frame} is the datatype used to associate key strings with
- at code{KvpValue} objects (@pxref{KvpValue}).
-
- at deftypefun kvp_frame* kvp_frame_new (void)
-Create and initialize a new @code{kvp_frame} object and return
-a pointer to it.
- at end deftypefun
-
- at deftypefun void kvp_frame_delete (kvp_frame * @var{frame})
-Free all memory associated with @var{frame}.
- at end deftypefun
-
- at deftypefun kvp_frame* kvp_frame_copy (const kvp_frame * frame)
-Return a deep copy of @var{frame}.
- at end deftypefun
-
- at deftypefun void kvp_frame_set_slot (kvp_frame * @var{frame}, const char * @var{key}, const KvpValue * @var{value})
-Associate @var{key} with @var{value} in @var{frame}.
- at end deftypefun
-
- at deftypefun void kvp_frame_set_slot_nc (kvp_frame * @var{frame}, const char * @var{key}, KvpValue * @var{value})
-Same as @code{kvp_frame_set_slot}, except that @var{value} is used
-directly, instead of being copied. This call transfers 'ownership'
-of @var{value} to @var{frame}.
- at end deftypefun
-
- at deftypefun KvpValue* kvp_frame_get_slot (kvp_frame * @var{frame}, const char * @var{key})
-Return the @code{KvpValue} object associated with @var{key}
-in @var{frame} or return @code{NULL} if there is no association
-for @var{key}. The value returned is not a copy.
- at end deftypefun
-
- at deftypefun void kvp_frame_set_slot_path (kvp_frame * @var{frame}, const KvpValue * @var{value}, const char * @var{first_key}, ...)
-Associate @var{value} with the ``key path'' specified by the variable
-argument list. Each key in the path except the last denotes a sub-frame
-which is associated with the given key. The variable list must be
-terminated with NULL.
- at end deftypefun
-
- at deftypefun void kvp_frame_set_slot_path_gslist (kvp_frame * @var{frame}, const KvpValue * @var{value}, GSList * @var{key_path})
-The same as @code{kvp_frame_set_slot_path}, except that the key path is
-specified using a GSList. All the keys in the list should be non-NULL.
- at end deftypefun
-
- at deftypefun {KvpValue *} kvp_frame_get_slot_path (kvp_frame * @var{frame}, const char * @var{first_key}, ...)
-Return the value associated with the key path, or @code{NULL} if none.
-The path is specified as in @code{kvp_frame_set_slot_path}.
- at end deftypefun
-
- at deftypefun {KvpValue *} kvp_frame_get_slot_path_gslist (kvp_frame * @var{frame}, GSList * @var{key_path})
-Return the value associated with the key path, or @code{NULL} if none.
-The path is specified as in @code{kvp_frame_set_slot_path_gslist}.
- at end deftypefun
-
- at deftypefun {kvp_frame *} kvp_frame_get_frame (kvp_frame * @var{frame}, ...)
-Works like @code{kvp_frame_get_slot_path}, but returns the last frame
-in the path. All the keys should refer to frames. If the frame path
-does not exist, it is created.
- at end deftypefun
-
- at deftypefun {kvp_frame *} kvp_frame_get_frame_gslist (kvp_frame * @var{frame}, GSList * @var{key_path})
-Works like @code{kvp_frame_get_slot_path_gslist}, but returns the last
-frame in the path. All the keys should refer to frames. If the frame
-path does not exist, it is created.
- at end deftypefun
-
- at deftypefun {kvp_frame *} kvp_frame_get_frame_slash (kvp_frame * @var{frame}, const char * @var{path})
-Works like @code{kvp_frame_get_frame}, but the frame path is specified
-as a single string where the keys are separated by slashes; thus, for
-example: @code{/this/is/a/valid/path} and @code{///so//is////this/}.
-Multiple slashes are compressed and a leading slash is optional. The
-pointers @code{.} and @code{..} are @emph{not} followed/obeyed. (This
-is arguably a bug that needs fixing).
- at end deftypefun
-
-
- at node KvpValue, kvp_list, kvp_frame, Key-Value Pair Frames
- at subsection KvpValue
- at tindex KvpValue
- at tindex kvp_value_t
-
-The @code{KvpValue} object stores the 'value' part of a key-value
-association in a @code{kvp_frame} object.
-
- at deftypefun void kvp_value_delete (KvpValue * @var{value})
-Free all of the memory associated with @var{value}.
- at end deftypefun
-
- at deftypefun KvpValue* kvp_value_copy (const KvpValue * @var{value})
-Return a deep copy of @var{value}.
- at end deftypefun
-
- at deftypefun kvp_value_t kvp_value_get_type (const KvpValue * @var{value})
-Return the type of value stored in @var{value}.
- at end deftypefun
-
-A @code{kvp_value_t} enum must have one of the following values:
-
- at table @code
-
- at item KVP_TYPE_NONE
-Indicates the absence of a value in a @code{kvp_frame}.
-
- at item KVP_TYPE_INT64
-A @code{gint64} value.
-
- at item KVP_TYPE_FLOAT64
-A @code{double} value.
-
- at item KVP_TYPE_STRING
-A @code{char *} value of arbitrary length.
-
- at item KVP_TYPE_GUID
-A @code{GUID} value. @xref{Globally Unique Identifiers}.
-
- at item KVP_TYPE_BINARY
-Arbitrary binary data.
-
- at item KVP_TYPE_LIST
-A @code{kvp_list} item which contains a list of @code{KvpValue} items.
-
- at item KVP_TYPE_FRAME
-A @code{kvp_frame} object. Thus, frames may contain other frames in a
-recursive manner.
-
- at end table
-
- at subsubsection Value Constructors
-
-The following functions create and return @code{KvpValue} objects with
-particular values. In the case of pointer arguments, deep copies are
-performed.
-
- at deftypefun KvpValue* kvp_value_new_int64 (gint64 @var{value})
- at end deftypefun
- at deftypefun KvpValue* kvp_value_new_float64 (double @var{value})
- at end deftypefun
- at deftypefun KvpValue* kvp_value_new_string (const char * @var{value})
- at end deftypefun
- at deftypefun KvpValue* kvp_value_new_guid (const GUID * @var{guid})
- at end deftypefun
- at deftypefun KvpValue* kvp_value_new_binary (const void * @var{data}, int @var{datasize})
- at end deftypefun
- at deftypefun KvpValue* kvp_value_new_list (const kvp_list * @var{value})
- at end deftypefun
- at deftypefun KvpValue* kvp_value_new_frame (const kvp_frame * @var{value});
- at end deftypefun
-
- at subsubsection Value Accessors
-
-The following functions access the value of a given @code{KvpValue}
-object. If the type of the object does not correspond to that named
-in the function, @code{NULL}, @code{0}, or @code{0.0} is returned
-as appropriate.
-
- at deftypefun gint64 kvp_value_get_int64 (const KvpValue * @var{value})
- at end deftypefun
- at deftypefun double kvp_value_get_float64 (const KvpValue * @var{value})
- at end deftypefun
- at deftypefun char* kvp_value_get_string (const KvpValue * @var{value})
- at end deftypefun
- at deftypefun GUID* kvp_value_get_guid (const KvpValue * @var{value})
- at end deftypefun
- at deftypefun void* kvp_value_get_binary (const KvpValue * @var{value}, int * @var{size_return})
- at end deftypefun
- at deftypefun kvp_list* kvp_value_get_list (const KvpValue * @var{value})
- at end deftypefun
- at deftypefun kvp_frame* kvp_value_get_frame (const KvpValue * @var{value})
- at end deftypefun
-
-
- at node kvp_list, , KvpValue, Key-Value Pair Frames
- at subsection kvp_list
- at tindex kvp_list
-
-A @code{kvp_list} object abstract a list of @code{KvpValue} objects.
-
- at deftypefun kvp_list* kvp_list_new ()
-Return a newly allocated @code{kvp_list} object.
- at end deftypefun
-
- at deftypefun void kvp_list_delete (kvp_list * @var{list})
-Free all memory associated with @var{list}, including the
- at code{KvpValue} objects in @var{list}.
- at end deftypefun
-
- at deftypefun kvp_list* kvp_list_copy (const kvp_list * @var{list})
-Return a deep copy of @var{list}.
- at end deftypefun
-
- at deftypefun gboolean kvp_list_null_p (const kvp_list * @var{list})
-Return @code{TRUE} if @var{list} is the empty list.
- at end deftypefun
-
- at deftypefun KvpValue* kvp_list_car (kvp_list * @var{list})
-If @var{list} is @code{NULL} or the empty list, return @code{NULL}.
-Otherwise, return the first @code{KvpValue} object in the list.
- at end deftypefun
-
- at deftypefun kvp_list* kvp_list_cdr (kvp_list * @var{list})
-If @var{list} is @code{NULL} or the empty list, return @code{NULL}.
-Otherwise, return a @code{kvp_list} object consisting of @var{list}
-with the first value removed. NOTE: the returned list is not a copy!
- at end deftypefun
-
- at deftypefun kvp_list* kvp_list_cons (KvpValue * @var{car}, kvp_list * @var{cdr})
-If either @var{car} or @var{cdr} is @code{NULL}, return @code{NULL}. Otherwise,
-return a @code{kvp_list} object consisting of the value of @var{car} followed
-by the values of @var{cdr}. This function uses 'hand-over' semantics, i.e.,
-the arguments @var{car} and @var{cdr} are no longer the responsibility of
-the caller and should not be accessed after the function returns.
- at end deftypefun
-
-
- at node Events, Commodities, Key-Value Pair Frames, Engine
- at section Events
-
-The Engine supports the concept of @dfn{Events} which notify
-external code when engine entities are created, modified, or
-destroyed.
-
-User code can register event handers which are invoked for each event,
-giving information about the specific engine entity generating the event
-and the nature of the event (creation, modification, or deletion).
-
-
- at menu
-* Event API::
- at end menu
-
-
- at node Event API, , Events, Events
- at subsection Event API
- at tindex GNCEngineEventType
-
-Engine events are classified using the @code{GNCEngineEventType}
-bitmask which has the following predefined values:
-
- at table @code
-
- at item GNC_EVENT_NONE
-A null value.
-
- at item GNC_EVENT_CREATE
-Indicates an entity has been created.
-
- at item GNC_EVENT_MODIFY
-Indicates an entity has been changed in some way.
-
- at item GNC_EVENT_DESTROY
-Indicates an entity is being destroyed.
-
- at item GNC_EVENT_ALL
-The boolean OR of @code{GNC_EVENT_CREATE}, @code{GNC_EVENT_MODIFY},
-and @code{GNC_EVENT_DESTROY}.
-
- at end table
-
-Event handlers are functions with the following type:
-
- at deftp {Data type} GNCEngineEventHandler void (*) (GUID * @var{entity}, GNCEngineEventType @var{event_type}, gpointer @var{user_data})
-A callback invoked when an engine event occurs. @var{entity} is the
- at code{GUID} of the entity generating the event. @var{event_type} is
-one of @code{GNC_EVENT_CREATE}, @code{GNC_EVENT_MODIFY}, or
- at code{GNC_EVENT_DESTROY}. @var{user_data} is the user data parameter
-supplied when the handler was registered.
- at end deftp
-
- at deftypefun gint gnc_engine_register_event_handler (GNCEngineEventHandler @var{handler}, gpointer @var{user_data})
-Register a handler for engine events. The return value is an identifier used
-to specify this handler in other API calls.
- at end deftypefun
-
- at deftypefun void gnc_engine_unregister_event_handler (gint @var{handler_id})
-Unregister the event handler specified by @var{handler_id}.
- at end deftypefun
-
- at deftypefun void gnc_engine_suspend_events (void)
-Suspend all engine events. This function may be called multiple
-times. To resume event generation, an equal number of calls to
- at code{gnc_engine_resume_events} must be made.
- at end deftypefun
-
- at deftypefun void gnc_engine_resume_events (void)
-Resume engine event generation.
- at end deftypefun
-
-
- at node Commodities, Commodity Tables, Events, Engine
- at section Commodities
- at tindex gnc_commodity
-
-A Commodity is the Engine abstraction of a tradable quantity,
-like a national currency or shares of a stock. A commodity
-object contains the following pieces of information:
-
- at table @asis
-
- at item A mnemonic name
-The `short' name for the commodity. For national currencies
-this is the 3-letter ISO4217 code (USD, AUD, etc.). For stocks
-this is generally the exchange symbol (RHAT, IBM, etc.).
-
- at item A namespace
-A string identifying the context in which the mnemonic is meaningful.
-
- at item A full name
-The `long' name for the commodity, such as "US Dollar" or "IBM Common
-Stock".
-
- at item A printable name
-The name used to print out a string describing the commodity to
-a user. This name is generally long -- in some contexts it may
-be better to use the mnemonic instead. The printable name is
-determined by the namespace and mnemonic.
-
- at item A unique name
-A canonical name for the commodity that cannot be identical to
-another commodity's unique name. The unique name is determined
-by the namespace and mnemonic.
-
- at item An exchange code
-A code used to identify the commodity in its namespace context.
-For example, stocks have a unique code assigned to them by the
-exchange they are listed on.
-
- at item A fraction
-An integer N which specifies that 1/N is generally the smallest
-fraction of the commodity which can be traded. For example, most
-currencies are tradable in 1/100ths, so the fraction would be 100.
-
- at end table
-
- at menu
-* General Commodity API::
-* Commodity Getters::
-* Commodity Setters::
- at end menu
-
-
- at node General Commodity API, Commodity Getters, Commodities, Commodities
- at subsection General Commodity API
-
- at deftypefun {gnc_commodity *} gnc_commodity_new (const char * @var{fullname}, const char * @var{namespace}, const char * @var{mnemonic}, const char * @var{exchange_code}, int @var{fraction})
-Create and return a new commodity object with the given values, or
- at code{NULL} if any of the values are invalid.
- at end deftypefun
-
- at deftypefun void gnc_commodity_destroy (gnc_commodity * @var{cm})
-Destroy the given commodity and free all associated memory.
- at end deftypefun
-
- at deftypefun gboolean gnc_commodity_equiv (const gnc_commodity * @var{a}, const gnc_commodity * @var{b})
-Return true if the two given commodities are equivalent. Two commodities
-are equivalent when they have the same namespace and the same mnemonic.
- at end deftypefun
-
-
- at node Commodity Getters, Commodity Setters, General Commodity API, Commodities
- at subsection Commodity Getters
-
- at deftypefun {const char *} gnc_commodity_get_mnemonic (const gnc_commodity * @var{cm})
-Return the mnemonic of @var{cm}.
- at end deftypefun
-
- at deftypefun {const char *} gnc_commodity_get_namespace (const gnc_commodity * @var{cm})
-Return the namespace of @var{cm}.
- at end deftypefun
-
- at deftypefun {const char *} gnc_commodity_get_fullname (const gnc_commodity * @var{cm})
-Return the full name of @var{cm}.
- at end deftypefun
-
- at deftypefun {const char *} gnc_commodity_get_printname (const gnc_commodity * @var{cm})
-Return the print name of @var{cm}.
- at end deftypefun
-
- at deftypefun {const char *} gnc_commodity_get_exchange_code (const gnc_commodity * @var{cm})
-Return the exchange code of @var{cm}.
- at end deftypefun
-
- at deftypefun {const char *} gnc_commodity_get_unique_name (const gnc_commodity * @var{cm})
-Return the unique name of @var{cm}.
- at end deftypefun
-
- at deftypefun int gnc_commodity_get_fraction (const gnc_commodity * @var{cm})
-Return the smallest tradable fraction of @var{cm}.
- at end deftypefun
-
-
- at node Commodity Setters, , Commodity Getters, Commodities
- at subsection Commodity Setters
-
- at deftypefun void gnc_commodity_set_mnemonic (gnc_commodity * @var{cm}, const char * @var{mnemonic})
-Set the mnemonic of @var{cm} to @var{mnemonic}.
- at end deftypefun
-
- at deftypefun void gnc_commodity_set_namespace (gnc_commodity * @var{cm}, const char * @var{namespace})
-Set the namespace of @var{cm} to @var{namespace}.
- at end deftypefun
-
- at deftypefun void gnc_commodity_set_fullname (gnc_commodity * @var{cm}, const char * @var{fullname})
-Set the fullname of @var{cm} to @var{fullname}.
- at end deftypefun
-
- at deftypefun void gnc_commodity_set_exchange_code (gnc_commodity * @var{cm}, const char * @var{exchange_code})
-Set the exchange code of @var{cm} to @var{exchange_code}.
- at end deftypefun
-
- at deftypefun void gnc_commodity_set_fraction (gnc_commodity * @var{cm}, int @var{smallest_fraction})
-Set the fraction of @var{cm} to @var{fraction}.
- at end deftypefun
-
-
- at node Commodity Tables, Prices, Commodities, Engine
- at section Commodity Tables
- at tindex gnc_commodity_table
-
-A Commodity Table holds a set of commodities and allows user code
-to add, remove, and access the commodities in the table.
-
-There is a single, global Commodity Table used by the Engine.
-
- at menu
-* General Commodity Table API::
-* Commodity Table Access API::
-* Commodity Table Modification API::
- at end menu
-
-
- at node General Commodity Table API, Commodity Table Access API, Commodity Tables, Commodity Tables
- at subsection General Commodity Table API
-
- at deftypefun {gnc_commodity_table *} gnc_commodity_table_new (void)
-Allocate and initialize a @code{gnc_commodity_table}. The returned
-table must be destroyed with @code{gnc_commodity_table_destroy}.
- at end deftypefun
-
- at deftypefun void gnc_commodity_table_destroy (gnc_commodity_table * @var{table})
-Destroy @var{table} and all associated resources, including all
-Commodity objects in the table.
- at end deftypefun
-
- at deftypefun {gnc_commodity_table *} gnc_engine_commodities (void)
-Return the global engine commodity table.
- at end deftypefun
-
-
- at node Commodity Table Access API, Commodity Table Modification API, General Commodity Table API, Commodity Tables
- at subsection Commodity Table Access API
-
- at deftypefun {gnc_commodity *} gnc_commodity_table_lookup (const gnc_commodity_table * @var{table}, const char * @var{namespace}, const char * @var{mnemonic})
-Look up a commodity in @var{table} given the namespace and the mnemonic.
-If no such commodity exists, @code{NULL} is returned.
- at end deftypefun
-
- at deftypefun {gnc_commodity *} gnc_commodity_table_find_full (const gnc_commodity_table * @var{table}, const char * @var{namespace}, const char * @var{fullnam}e)
-Look up a commodity in @var{table} given the namespace and the full name.
-If no such commodity exists, @code{NULL} is returned.
- at end deftypefun
-
- at deftypefun int gnc_commodity_table_has_namespace (const gnc_commodity_table * @var{table}, const char * @var{namespace})
-Return true if @var{table} has the namespace @var{namespace}.
- at end deftypefun
-
- at deftypefun guint gnc_commodity_table_get_size (gnc_commodity_table * @var{table})
-Return the total number of commodities stored in @var{table}.
- at end deftypefun
-
- at deftypefun guint gnc_commodity_table_get_number_of_namespaces (gnc_commodity_table * @var{table})
-Return the number of distinct namespaces in @var{table}.
- at end deftypefun
-
- at deftypefun {GList *} gnc_commodity_table_get_namespaces (const gnc_commodity_table * @var{table})
-Return a list of the distinct namespaces in @var{table}. The list should
-be freed with @code{g_list_free} but the namespaces should not be freed
-or modified.
- at end deftypefun
-
- at deftypefun {GList *} gnc_commodity_table_get_commodities (const gnc_commodity_table * @var{table}, const char * @var{namespace})
-Return a list of the commodities under @var{namespace} in @var{table}.
-The list should be freed with @code{g_list_free} but the commodities
-should not be freed.
- at end deftypefun
-
-
- at node Commodity Table Modification API, , Commodity Table Access API, Commodity Tables
- at subsection Commodity Table Modification API
-
- at deftypefun {gnc_commodity *} gnc_commodity_table_insert (gnc_commodity_table * @var{table}, gnc_commodity * @var{comm})
-Add commodity @var{comm} to @var{table}. If @var{comm}'s namespace is
-not in @var{table}, the namespace will be added. This function has
-hand-over semantics, i.e., @var{table} assumes responsibility for
- at var{comm}. @var{comm} may even be destroyed by this call! The function
-returns the actual commodity added as a result of the call. It may not
-be the same object as @var{comm}, but will be equivalent to @var{comm}.
- at end deftypefun
-
- at deftypefun void gnc_commodity_table_remove (gnc_commodity_table * @var{table}, gnc_commodity * @var{comm})
-Remove the given commodity from @var{table}. @var{comm} is not modified
-or destroyed.
- at end deftypefun
-
- at deftypefun void gnc_commodity_table_add_namespace (gnc_commodity_table * @var{table}, const char * @var{namespace})
-Add @var{namespace} to @var{table}.
- at end deftypefun
-
- at deftypefun void gnc_commodity_table_delete_namespace (gnc_commodity_table * @var{table}, const char * @var{namespace})
-Delete @var{namespace} from @var{table} including all associated
-commodities.
- at end deftypefun
-
- at deftypefun void gnc_commodity_table_remove_non_iso (gnc_commodity_table * @var{table})
-Remove and destroy all commodities in @var{table} which are not in the
-ISO4217 namespace.
- at end deftypefun
-
-
- at node Prices, Price Databases, Commodity Tables, Engine
- at section Prices
- at tindex GNCPrice
-
-A Price is the Engine abstraction of an "instantaneous" price quote for a
-given commodity with respect to another commodity. For example, a given
-price might represent the value of LNUX in USD on 2001-02-03. A Price
-contains the following pieces of information:
-
- at table @asis
-
- at item A GUID
-A GUID uniquely identifying the GNCPrice.
-
- at item A commodity
-The commodity being priced.
-
- at item A currency
-The denomination of the value of the item being priced.
-
- at item A value
-The value of the item being priced.
-
- at item A time
-The time the price was valid.
-
- at item A source
-A string describing the source of the quote. These strings will have a
-form like this: "Finance::Quote", "user:misc", "user:foo", etc. If the
-quote came from a user, as a matter of policy, you @emph{must} prefix
-the string you give with "user:". For now, the only other reserved
-values are "Finance::Quote" and "old-file-import".
-
- at item A type
-A string describing the type of quote -- types possible right now are
-"bid", "ask", "last", "nav", and "unknown".
-
- at end table
-
-
- at menu
-* Price Implementation Details::
-* General Price API::
-* Price Getters::
-* Price Setters::
- at end menu
-
-
- at node Price Implementation Details, General Price API, Prices, Prices
- at subsection Price Implementation Details
-
-For the source and type fields, @code{NULL} and the empty string are
-considered the same, so if one of these is the empty string then it
-might be @code{NULL} after a file save/restore.
-
-GNCPrices are reference counted. When you create a price or or clone
-one, the new price's reference count is set to 1. When you are finished
-with a price, call @code{gnc_price_unref}. If you hand the price pointer
-to some other code that needs to keep it, make sure it calls
- at code{gnc_price_ref} to indicate its interest in that price, and calls
- at code{gnc_price_unref} when it's finished with the price. For those
-unfamiliar with reference counting, basically each price stores an
-integer count which starts at 1 and is incremented every time someone
-calls @code{gnc_price_ref}. Conversely, the count is decremented every
-time someone calls @code{gnc_price_unref}. If the count ever reaches 0,
-the price is destroyed.
-
-All of the getters return data that's internal to the GNCPrice,
-not copies, so don't free or modify these values.
-
-All of the setters store copies of the data given, with the exception of
-the commodity field which just stores the pointer given. It is assumed
-that commodities are a global resource and are pointer unique.
-
-
- at node General Price API, Price Getters, Price Implementation Details, Prices
- at subsection General Price API
-
- at deftypefun {GNCPrice *} gnc_price_create (void)
-Return a newly allocated and initialized price with a reference count of
-1. The price should be dereferenced with @code{gnc_price_unref} when no
-longer needed, but the price should not be freed by user code.
- at end deftypefun
-
- at deftypefun {GNCPrice *} gnc_price_clone (GNCPrice * @var{p})
-Return a newly allocated price that's a content-wise duplicate of
- at var{p}. The returned clone will have a reference count of 1.
- at end deftypefun
-
- at deftypefun void gnc_price_ref (GNCPrice * @var{p})
-Increase the reference count of @var{p} by 1.
- at end deftypefun
-
- at deftypefun void gnc_price_unref (GNCPrice * @var{p})
-Decrease the reference coutn of @var{p} by 1. If the
-resulting count is 0, @var{p} will be destroyed.
- at end deftypefun
-
- at deftypefun {GNCPrice *} gnc_price_lookup (const GUID * @var{guid})
-Lookup and return the price associated with @var{guid}, or @code{NULL}
-if there is no such price.
- at end deftypefun
-
-
- at node Price Getters, Price Setters, General Price API, Prices
- at subsection Price Getters
-
- at deftypefun {const GUID *} gnc_price_get_guid (GNCPrice * @var{p})
-Return the GUID of @var{p}.
- at end deftypefun
-
- at deftypefun {gnc_commodity *} gnc_price_get_commodity (GNCPrice * @var{p})
-Return the commodity of @var{p}.
- at end deftypefun
-
- at deftypefun {gnc_commodity *} gnc_price_get_currency (GNCPrice * @var{p})
-Return the currency of @var{p}.
- at end deftypefun
-
- at deftypefun time64 gnc_price_get_time64 (GNCPrice * @var{p})
-Return the time of @var{p}.
- at end deftypefun
-
- at deftypefun {const char *} gnc_price_get_source (GNCPrice * @var{p})
-Return the source of @var{p}.
- at end deftypefun
-
- at deftypefun {const char *} gnc_price_get_type (GNCPrice * @var{p})
-Return the type of @var{p}.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_price_get_value (GNCPrice * @var{p})
-Return the value of @var{p}.
- at end deftypefun
-
- at deftypefun gint32 gnc_price_get_version (GNCPrice * @var{p})
-Return the version of @var{p}.
- at end deftypefun
-
-
- at node Price Setters, , Price Getters, Prices
- at subsection Price Setters
-
-Invocations of the setters should be wrapped with calls to
- at code{gnc_price_begin_edit} and @code{gnc_price_commit_edit}. The
-begin/commit calls help ensure that the local price db is synchronized
-with the backend.
-
- at deftypefun void gnc_price_begin_edit (GNCPrice * @var{p})
-Begin a sequence of changes to @var{p}.
- at end deftypefun
-
- at deftypefun void gnc_price_commit_edit (GNCPrice * @var{p})
-End a sequence of changes to @var{p}.
- at end deftypefun
-
- at deftypefun void gnc_price_set_commodity (GNCPrice * @var{p}, gnc_commodity * @var{c})
-Set the commodity of @var{p} to @var{c}.
- at end deftypefun
-
- at deftypefun void gnc_price_set_currency (GNCPrice * @var{p}, gnc_commodity * @var{c})
-Set the currency of @var{p} to @var{c}.
- at end deftypefun
-
- at deftypefun void gnc_price_set_time64 (GNCPrice * @var{p}, time64 @var{t})
-Set the time of @var{p} to @var{t}.
- at end deftypefun
-
- at deftypefun void gnc_price_set_source (GNCPrice * @var{p}, const char * @var{source})
-Set the source of @var{p} to @var{source}.
- at end deftypefun
-
- at deftypefun void gnc_price_set_type (GNCPrice * @var{p}, const char * @var{type})
-Set the type of @var{p}to @var{type}.
- at end deftypefun
-
- at deftypefun void gnc_price_set_value (GNCPrice * @var{p}, gnc_numeric @var{value})
-Set the value of @var{p} to @var{value}.
- at end deftypefun
-
- at deftypefun void gnc_price_set_version (GNCPrice * @var{p}, gint32 @var{versn})
-Set the version of @var{p} to @var{versn}.
- at end deftypefun
-
-
- at node Price Databases, Splits, Prices, Engine
- at section Price Databases
- at tindex GNCPriceDB
-
-A Price Database stores GNCPrices and allows prices to be looked
-up based on currency, commodity, and time.
-
-
- at menu
-* Price Lists::
-* General Price Database API::
- at end menu
-
-
- at node Price Lists, General Price Database API, Price Databases, Price Databases
- at subsection Price Lists
-
-Price Lists are used by Price Databases to organize prices for a given
-commodity and currency. A Price List is a list of prices with the same
-commodity and currency, sorted by decreasing time (earlier prices come
-later in the list).
-
- at deftypefun gboolean gnc_price_list_insert (GList ** @var{prices}, GNCPrice * @var{p})
-Insert price @var{p} into the list @var{prices}, calling
- at var{gnc_price_ref} on @var{p} during the process.
- at end deftypefun
-
- at deftypefun gboolean gnc_price_list_remove (GList ** @var{prices}, GNCPrice * @var{p})
-Remove price @var{p} from the list @var{prices}, calling
- at code{gnc_price_unref} on @var{p} during the process.
- at end deftypefun
-
- at deftypefun void gnc_price_list_destroy (GList * @var{prices})
-Destroy the price list @var{prices}, calling @code{gnc_price_unref}
-on all the prices in the list.
- at end deftypefun
-
-
- at node General Price Database API, , Price Lists, Price Databases
- at subsection General Price Database API
-
- at deftypefun {GNCPriceDB *} gnc_pricedb_create (void)
-Create and return a new price database.
- at end deftypefun
-
- at deftypefun void gnc_pricedb_destroy (GNCPriceDB * @var{db})
-Destroy the price database @var{db} and unreference all of
-the prices it contains. This may not deallocate all of those
-prices; other code may still be holding references to them.
- at end deftypefun
-
- at deftypefun gboolean gnc_pricedb_add_price (GNCPriceDB * @var{db}, GNCPrice * @var{p})
-Add the price @var{p} to @var{db}. This will increase the
-reference count of @var{p}, so user code may safely drop
-its reference to the price (i.e. call @code{gnc_price_unref})
-if the call succeeds (returns true).
- at end deftypefun
-
- at deftypefun gboolean gnc_pricedb_remove_price (GNCPriceDB * @var{db}, GNCPrice * @var{p})
-Removes the price @var{p} from the price database @var{db}. Returns true
-if successful and false otherwise.
- at end deftypefun
-
-
- at node Splits, Transactions, Price Databases, Engine
- at section Splits
- at tindex Split
-
-A Split is the Engine abstraction of an accounting entry in an Account
-Ledger. In accounting terms, a Split is a Ledger Entry. As such, it
-contains the following pieces of information:
-
- at table @asis
-
- at item A parent Account
-The Account of which it is an entry.
-
- at item A parent Transaction.
-In accounting terms, this is the Journal Entry which this Ledger Entry
-is linked to.
-
- at item A 'share quantity'
-This is the number of 'shares' which have been debited to the parent
-Account. This quantity may be negative, in which case the Split
-represents a 'credit'. Shares are given in units of the security of the
-Account, unless the security field is NULL, in which case shares are
-given in units of the Account currency. @xref{Accounts}.
-
- at item A 'value'
-This represents the value of the shares in units of the currency of
-the Account. If the currency and the security are the same, or the
-security field is NULL, the value and share quantity must be equal.
-
- at item A 'reconciled' flag
-This flag represents the reconciled status of the Split. Possible
-reconciliation states for a Split are:
-
- @table @asis
-
- @item Not Reconciled
- The Split has not been reconciled or cleared.
-
- @item Cleared
- The Split has been cleared, but not reconciled.
-
- @item Reconciled
- The Split has been reconciled with a statement.
-
- @item Frozen
- The Split has been frozen into the accounting period.
-
- @end table
-
- at end table
-
-In addition to the above, Splits contain a Memo field, an Action
-field, and a key-value pair frame. The Memo and Action fields are for
-arbitrary user input. See src/engine/kvp_frame.txt for the names of
-keys that have already been reserved for use in the frame.
-
-
- at menu
-* General Split API::
-* Split Getters::
-* Split Setters::
- at end menu
-
- at node General Split API, Split Getters, Splits, Splits
- at subsection General Split API
-
- at deftypefun {Split *} xaccMallocSplit (void)
-Allocate, initialize, and return a new Split.
- at end deftypefun
-
- at deftypefun void xaccSplitDestroy (Split * @var{split})
-Update @var{split}'s parent Account and Transaction in a consistent
-manner, completely unlinking of @var{split} and freeing its memory. The
-goal of this routine is to perform the removal and destruction of the
-Split in an atomic fashion, with no chance of accidentally leaving the
-accounting structure out-of-balance or otherwise inconsistent.
-
-If the deletion of the Split leaves the Transaction with no Splits, then
-the Transaction will be marked for deletion, but will not be deleted
-until the @code{xaccTransCommitEdit()} routine is called.
- at end deftypefun
-
- at deftypefun {const GUID *} xaccSplitGetGUID (Split * @var{split})
-Return the GUID of @var{split}.
- at end deftypefun
-
- at deftypefun {Split *} xaccSplitLookup (const GUID * @var{guid})
-Return the split associated with @var{GUID}, or @code{NULL} if there is
-no such split.
- at end deftypefun
-
- at deftypefun void xaccSplitMakeStockSplit (Split * @var{split})
-Modify @var{split} to be an ``official'' stock-split split. Among other
-things, this involves clearing the value of the split to 0.
- at end deftypefun
-
-
- at node Split Getters, Split Setters, General Split API, Splits
- at subsection Split Getters
-
- at deftypefun {Account *} xaccSplitGetAccount (Split * @var{split})
-Return the parent Account of @var{split}.
- at end deftypefun
-
- at deftypefun {Transaction *} xaccSplitGetParent (Split * @var{split})
-Return the parent Transaction of @var{split}.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetShareAmount (Split * @var{split})
-Return the 'share quantity' of @var{split}.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetSharePrice (Split * @var{split})
-Return the 'share price' of @var{split}, which is the value
-divided by the share quantity.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetValue (Split * @var{split})
-Return the value of @var{split}.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetBaseValue (Split * @var{split}, const char * @var{base_currency})
-Return either the share quantity or the value of @var{split}, depending
-upon whether @var{base_currency} matches the security or currency of the
-parent Account, respectively. No other value for @var{base_currency} is
-legal.
- at end deftypefun
-
- at deftypefun char xaccSplitGetReconcile (Split * @var{split})
-Return the value of the reconcile flag in @var{split}. Possible
-values for the flag are:
-
- @table @code
-
- @item NREC
- Not Reconciled
-
- @item CREC
- Cleared
-
- @item YREC
- Reconciled
-
- @item FREC
- Frozen
-
- @end table
-
- at end deftypefun
-
- at deftypefun void xaccSplitGetDateReconciledTS (Split * @var{split}, Timespec * @var{ts})
-Fill @var{ts} with the reconciled date of @var{split}.
- at end deftypefun
-
- at deftypefun {const char *} xaccSplitGetMemo (Split * @var{split})
-Return the Memo field of @var{split}.
- at end deftypefun
-
- at deftypefun {const char *} xaccSplitGetAction (Split * @var{split})
-Return the Action field of @var{split}.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetBalance (Split * @var{split})
-Return the balance of @var{split}'s parent Account up to and including
- at var{split}. See @ref{Accounts} for details.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetClearedBalance (Split * @code{split})
-Return the cleared balance of @var{split}'s parent Account up to and
-including @var{split}. See @ref{Accounts} for details.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetReconciledBalance (Split * @code{split})
-Return the reconciled balance of @var{split}'s parent Account up to and
-including @var{split}. See @ref{Accounts} for details.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetShareBalance (Split * @var{split})
-Return the share balance of @var{split}'s parent Account up to and
-including @var{split}. See @ref{Accounts} for details.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetShareClearedBalance (Split * @code{split})
-Return the share cleared balance of @var{split}'s parent Account up to
-and including @var{split}. See @ref{Accounts} for details.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetShareReconciledBalance (Split * @code{split})
-Return the share reconciled balance of @var{split}'s parent Account up
-to and including @var{split}. See @ref{Accounts} for details.
- at end deftypefun
-
- at deftypefun {const char*} xaccSplitGetType (Split * @var{split})
-Return @var{split}'s type as a string. Currently, the possibilities are
-
- @table @code
- @item normal
- a normal split -- the default.
-
- @item stock-split
- a split representing a stock split. The value should be 0 and the
- share amount should represent the number of shares added/subtracted from
- the account as a result of the forward/reverse stock split.
- @end table
-
- at end deftypefun
-
-
- at node Split Setters, , Split Getters, Splits
- at subsection Split Setters
-
- at deftypefun void xaccSplitSetMemo (Split * @var{split}, const char * @var{memo})
-Set the memo field of @var{split} to @var{memo}.
- at end deftypefun
-
- at deftypefun void xaccSplitSetAction (Split * @var{split}, const char * @var{action})
-Set the action field of @var{split} to @var{memo}. The action field is
-an arbitrary string, but is intended to be conveniently limited to a
-menu of selections such as "Buy", "Sell", "Interest", etc.
- at end deftypefun
-
- at deftypefun void xaccSplitSetReconcile (Split * @var{split}, char @var{reconciled_flag})
-Set the reconciled flag of @var{split} to @var{reconciled_flag}. For the
-possible values and meanings of @var{reconciled_flag}, see @ref{Split Getters}.
- at end deftypefun
-
- at deftypefun void xaccSplitSetDateReconciledSecs (Split * @var{split}, time_t @var{time})
-Set the reconciliation date of @var{split} to @var{time}.
- at end deftypefun
-
- at deftypefun void xaccSplitSetDateReconciledTS (Split * @var{split}, Timespec * @var{ts})
-Set the reconciliation date of @var{split} to @var{ts}.
- at end deftypefun
-
- at deftypefun void xaccSplitSetShareAmount (Split * @var{split}, gnc_numeric amount)
-Set the share quantity of @var{split} to @var{amount}.
- at end deftypefun
-
- at deftypefun void xaccSplitSetSharePrice (Split * @var{split}, gnc_numeric @var{price})
-Set the share price of @var{split} to @var{price}.
- at end deftypefun
-
- at deftypefun void xaccSplitSetSharePriceAndAmount (Split * @var{split}, gnc_numeric @var{price}, gnc_numeric @var{amount})
-Set both the share price and share quantity of @var{split}. This routine
-is more efficient than calling @code{xaccSplitSetShareAmount} and
- at code{xaccSplitSetSharePrice} in succession.
- at end deftypefun
-
- at deftypefun void xaccSplitSetValue (Split * @var{split}, gnc_numeric @var{value})
-Adjust the share quantity of @var{split} so that @var{split}'s value is
-equal to @var{value}.
- at end deftypefun
-
- at deftypefun void xaccSplitSetBaseValue (Split * @var{split}, gnc_numeric @var{value}, const char * @var{base_currency})
-Set either the share quantity or value of @var{split} depending upon
-whether @var{base_currency} is the security or current of @var{split}'s
-parent Account. @xref{Accounts}.
- at end deftypefun
-
-
- at node Transactions, Accounts, Splits, Engine
- at section Transactions
- at tindex Transaction
-
-A Transaction is the Engine abstraction of an accounting entry in a
-Journal. In accounting terms, a Transaction is a Journal Entry. As
-such, it contains the following pieces of information:
-
- at table @asis
-
- at item A list of Ledger Entries, or Splits
-The list of debits and credits which make up this Transaction. As in
-accounting, a Transaction is balanced when the sum of the debits equals
-the sum of the credits.
-
- at item The entry date
-The date the transaction was entered into GnuCash.
-
- at item The post date
-The date the transaction was posted. This is often the date the
-transaction was recorded by the bank, or the date the user initiated
-the transaction (i.e., wrote the check, made the ATM withdrawal).
-
- at item A transaction number field
-This field is intended to hold a transaction number, such as a
-check number or an ID assigned by a bank to an electronic transfer.
-
- at item A description
-A textual description of the transaction.
-
- at end table
-
-In addition to the above, Transactions contain a key-value pair frame.
-
-
- at subsection The Transaction Edit Cycle
-
-The Engine supports (and, in fact, requires) a 2-phase commit/rollback
-cycle for modifying Transactions and their constituent Splits. A Transaction
-must be opened for editing using @code{xaccTransBeginEdit()} before any of
-the following actions may be taken.
-
- at itemize
-
- at item
-Modifying any field of a Transaction.
-
- at item
-Modifying any Split belonging to the Transaction. That includes
-re-parenting a Split to a different Account or a different Transaction.
-In the case of re-parenting to a new Transaction, both Transactions must
-be opened for editing.
-
- at item
-Deleting any Split belonging to the Transaction.
-
- at item
-Adding a Split to the transaction.
-
- at item
-Deleting the Transaction.
-
- at end itemize
-
-After the desired changes have been made, they must either be committed
-using @code{xaccTransCommitEdit()} or rolled back using
- at code{xaccTransRollbackEdit()}. Rolling back a transaction will undo any
-changes which have been made to it or to its Splits since it was opened
-for editing.
-
-
- at menu
-* General Transaction API::
-* Transaction Getters::
-* Transaction Setters::
- at end menu
-
-
- at node General Transaction API, Transaction Getters, Transactions, Transactions
- at subsection General Transaction API
-
- at deftypefun {Transaction *} xaccMallocTransaction (void)
-Allocate, initialize, and return a new Transaction.
- at end deftypefun
-
- at deftypefun void xaccTransDestroy (Transaction * {trans})
-Remove all of the Splits from each of their accounts and free the memory
-associated with them. This routine must be followed by either an
- at code{xaccTransCommitEdit()} in which case the transaction memory will
-be freed, or by @code{xaccTransRollbackEdit()}, in which case all the
-original Splits are put back into place.
- at end deftypefun
-
- at deftypefun void xaccTransAppendSplit (Transaction * @var{trans}, Split * @var{split})
-Append @var{split} to the collection of Splits in @var{trans}. If the
-Split is already a part of another Transaction, it will be removed from
-that Transaction first.
- at end deftypefun
-
- at deftypefun void xaccTransBeginEdit (Transaction * @var{trans})
-This method must be called before any changes are made to @var{trans} or
-any of its component Splits. If this is not done, errors will result.
- at end deftypefun
-
- at deftypefun void xaccTransCommitEdit (Transaction * @var{trans})
-This method indicates that the changes to @var{trans} and its Splits are
-complete and should be made permanent. Note this routine may result in
-the deletion of the transaction, if the Transaction is "empty" (has no
-Splits) or if @code{xaccTransDestroy()} was called on the Transaction.
- at end deftypefun
-
- at deftypefun void xaccTransRollbackEdit (Transaction * @var{trans})
-Rejects all changes made to @var{trans} and its Splits, and sets
- at var{trans} back to where it was before the @code{xaccTransBeginEdit()}
-call. This includes restoring any deleted Splits, removing any added
-Splits, and undoing the effects of @code{xaccTransDestroy()}, as well
-as restoring share quantities, memos, descriptions, etc.
- at end deftypefun
-
- at deftypefun gboolean xaccTransIsOpen (Transaction * @var{trans})
-Return @code{TRUE} if @var{trans} is open for editing. Otherwise, it
-returns @code{FALSE}.
- at end deftypefun
-
- at deftypefun {const GUID *} xaccTransGetGUID (Transaction * @var{trans})
-Return the GUID of @var{trans}.
- at end deftypefun
-
- at deftypefun {Transaction *} xaccTransLookup (const GUID * @var{guid})
-Return the Transaction associated with @var{GUID}, or @code{NULL} if
-there is no such Transaction.
- at end deftypefun
-
- at deftypefun {KvpValue *} xaccTransGetSlot (Transaction * @var{trans}, const char * @var{key})
-Return the @code{KvpValue} associated with @var{key} in @var{trans}.
-If there is none, @code{NULL} is returned.
- at end deftypefun
-
- at deftypefun void xaccTransSetSlot (Split * @var{trans}, const char * @var{key}, const KvpValue * @var{value})
-Associate a copy of @var{value} with @var{key} in @var{trans}.
- at end deftypefun
-
-
- at node Transaction Getters, Transaction Setters, General Transaction API, Transactions
- at subsection Transaction Getters
-
- at deftypefun {Split *} xaccTransGetSplit (Transaction * @var{trans}, int @var{i})
-Return the @var{I}th Split of @var{trans}.
- at end deftypefun
-
- at deftypefun {GList *} xaccTransGetSplitList (Transaction * @var{trans})
-Return a @code{GList} of the Splits in @var{trans}. This list is owned
-by @var{trans} and should not be modified in any way!
- at end deftypefun
-
- at deftypefun {const char *} xaccTransGetNum (Transaction * @var{trans})
-Return the number field of @var{trans}.
- at end deftypefun
-
- at deftypefun {const char *} xaccTransGetDescription (Transaction * @var{trans})
-Return the description field of @var{trans}.
- at end deftypefun
-
- at deftypefun time_t xaccTransGetDate (Transaction * @var{trans})
-Return the post date of @var{trans} as a @code{time_t} value.
- at end deftypefun
-
- at deftypefun {long long} xaccTransGetDateL (Transaction * @var{trans})
-Return the post date of @var{trans} as a @code{long long} value.
- at end deftypefun
-
- at deftypefun void xaccTransGetDateTS (Transaction * @var{trans}, Timespec * @var{ts})
-Return the post date of @var{trans} in @var{ts}.
- at end deftypefun
-
- at deftypefun void xaccTransGetDateEnteredTS (Transaction * @var{trans}, Timespec * @var{ts})
-Return the entry date of @var{trans} in @var{ts}.
- at end deftypefun
-
- at deftypefun {char *} xaccTransGetDateStr (Transaction * @var{trans})
-Return a string representing the post date of @var{trans}, or NULL if
- at var{trans} is NULL. The string must be freed with @code{free()} after
-use.
- at end deftypefun
-
- at deftypefun int xaccTransCountSplits (Transaction * @var{trans})
-Return the number of Splits in @var{trans}.
- at end deftypefun
-
-
- at node Transaction Setters, , Transaction Getters, Transactions
- at subsection Transaction Setters
-
-Remember, before you modify a Transaction, you must open it for editing
-with @code{xaccTransBeginEdit}.
-
- at deftypefun void xaccTransSetDate (Transaction * @var{trans}, int @var{day}, int @var{mon}, int @var{year})
-Set the post date of @var{trans} with @var{day}, @var{month}, and @var{year}.
- at end deftypefun
-
- at deftypefun void xaccTransSetDateSecs (Transaction * @var{trans}, time_t @var{time})
-Set the post date of @var{trans} using a @code{time_t} value.
- at end deftypefun
-
- at deftypefun void xaccTransSetDateToday (Transaction * @var{trans})
-Set the post date of @var{trans} to the current time.
- at end deftypefun
-
- at deftypefun void xaccTransSetDateTS (Transaction * @var{trans}, const Timespec * @var{ts})
-Set the post date of @var{trans} from @var{ts}.
- at end deftypefun
-
- at deftypefun void xaccTransSetDateEnteredSecs (Transaction *trans, time_t time)
-Set the entry date of @var{trans} from a @code{time_t} value.
- at end deftypefun
-
- at deftypefun void xaccTransSetDateEnteredTS (Transaction * @var{trans}, const Timespec * @var{ts})
-Set the entry date of @var{trans} from @var{ts}.
- at end deftypefun
-
- at deftypefun void xaccTransSetNum (Transaction * @var{trans}, const char * @var{num})
-Set the number field of @var{trans} to @var{num}.
- at end deftypefun
-
- at deftypefun void xaccTransSetDescription (Transaction * @var{trans}, const char * @var{desc})
-Set the description field of @var{trans} to @var{desc}.
- at end deftypefun
-
-
- at node Accounts, Account Groups, Transactions, Engine
- at section Accounts
- at tindex Account
-
-An Account is the Engine abstraction of an, well, an account. Accounts
-contain the following pieces of information:
-
- at table @asis
-
- at item A list of Ledger Entries, or Splits
-The list of debits and credits which apply to the Account. The sum of
-all debits and credits is the account balance.
-
- at item A type
-An integer code identifying the type of account. The Account type
-determines whether the Account holds shares valued in a currency
-or not. It is also used by the GUI and reporting system to determine
-how debits & credits to the Account should be treated and displayed.
-
- at item A name
-The name of the Account.
-
- at item An account code
-A string that is intended to hold a unique user-selected identifier
-for the account. However, uniqueness of this field is not enforced.
-
- at item A description
-A textual description of the Account.
-
- at item A currency
-The commodity that Splits in the account are valued in, i.e., the
-denomination of the 'value' member of Splits in the account.
-
- at item A curreny SCU
-The SCU is the smallest convertible unit that the currency is
-traded in. This value overrides the default SCU of the currency.
-
- at item A security
-For Accounts which may contain shares (such as stock accounts),
-the denomination of the 'share quantity' member of Splits in
-the accounts. For accounts which do not contain shares, the
-security is blank, and the share quantities are denominated
-in the Account currency.
-
- at item A security SCU
-Analogous to the currency SCU, but for the security.
-
- at item A parent and child Account Group.
-The parent and child of an Account are Account Groups
-(@pxref{Account Groups}). Account Groups are used to
-connect Accounts together into an Account hierarchy.
-If the parent Account Group is not present, the Account
-is at the top level of the hierarchy. If the child
-Account Group is not present, the Account has no
-children.
-
- at end table
-
-In addition to the above, Accounts contain a key-value pair frame.
-
- at menu
-* Account Types::
-* General Account API::
-* Account Type API::
-* Account Getters::
-* Account Tax API::
- at end menu
-
-
- at node Account Types, General Account API, Accounts, Accounts
- at subsection Account Types
- at tindex GNCAccountType
-
-Account Types are defined by the @code{GNCAccountType} enumeration.
-Possible values are:
-
- @table @code
-
- @item BAD_TYPE, NO_TYPE
- Both of these values indicate an illegal Account type.
-
- @item BANK
- Denotes a savings or checking account held at a bank.
- Such an account is often interest bearing.
-
- @item CASH
- Denotes a shoe-box or pillowcase stuffed with cash. In other
- words, actual currency held by the user.
-
- @item CREDIT
- Denotes credit card accounts.
-
- @item ASSET
- Denotes a generic asset account.
-
- @item LIABILITY
- Denotes a generic liability account.
-
- @item STOCK
- A stock account containing stock shares.
-
- @item MUTUAL
- A mutual fund account containing fund shares.
-
- @item CURRENCY
- Denotes a currency trading account. In many ways, a currency trading
- account is like a stock trading account, where both quantities
- and prices are set. However, generally both currency and security
- are national currencies.
-
- @item INCOME
- Denotes an income account. The GnuCash financial model does not
- use 'categories'. Actual accounts are used instead.
-
- @item EXPENSE
- Denotes an expense account.
-
- @item EQUITY = 10,
- Denotes an equity account.
-
- @end table
-
-
- at node General Account API, Account Type API, Account Types, Accounts
- at subsection General Account API
-
- at deftypefun {Account *} xaccMallocAccount (void)
-Allocate and initialize an Account. The account must be
-destroyed by calling @code{xaccAccountBeginEdit} followed
-by @code{xaccAccountDestroy}.
- at end deftypefun
-
- at deftypefun void xaccAccountDestroy (Account * @var{account})
-Destroys @var{account} and frees all memory associated with
-it. This routine will also destroy the Account's children.
-You must call @code{xaccAccountBeginEdit} before calling
-this function.
- at end deftypefun
-
- at deftypefun void xaccAccountBeginEdit (Account * @var{account})
-This routine, together with @code{xaccAccountCommitEdit},
-provide a two-phase-commit wrapper for account updates
-much in the same way as @var{xaccTransBeginEdit} and
- at var{xaccTransCommitEdit} do for Transactions.
- at end deftypefun
-
- at deftypefun void xaccAccountCommitEdit (Account * @var{account})
-The counterpart to @var{xaccAccountBeginEdit}.
- at end deftypefun
-
- at deftypefun {Account *} xaccCloneAccountSimple (const Account * @var{from})
-Return a 'copy' of @var{from} that is identical in the type, name, code,
-description, kvp data, and currency. All other fields are the same as an
-account returned by @code{xaccMallocAccount}.
- at end deftypefun
-
- at deftypefun {const GUID *} xaccAccountGetGUID (Account * @var{account})
-Return the globally unique id associated with @var{account}.
- at end deftypefun
-
- at deftypefun {Account *} xaccAccountLookup (const GUID * @var{guid})
-Return the Account associated with @var{guid}, or NULL if there is
-no such Account.
- at end deftypefun
-
- at deftypefun {kvp_frame *} xaccAccountGetSlots (Account * @var{account})
-Return the @code{kvp_frame} associated with @var{account}. User code
-may modify this @code{kvp_frame}, but must not destroy it.
- at end deftypefun
-
- at deftypefun void xaccAccountSetSlots_nc (Account * @var{account}, kvp_frame * @var{frame})
-Set the @code{kvp_frame} associated with @var{account}. After the call,
- at var{frame} is owned by @var{account}, so don't destroy it.
- at end deftypefun
-
-
- at node Account Type API, Account Getters, General Account API, Accounts
- at subsection Account Type API
-
- at deftypefun {const char *} xaccAccountGetTypeStr (GNCAccountType @var{type})
-Return a string corresponding to the given Account type suitable for
-display by a GUI. The string is translated with gettext according to
-the current locale.
- at end deftypefun
-
- at deftypefun {char *} xaccAccountTypeEnumAsString (GNCAccountType @var{type})
-Return a string corresponding to the given Account type. The string
-is not translated and is independent of the current locale.
- at end deftypefun
-
- at deftypefun gboolean xaccAccountStringToType (const char * @var{str}, GNCAccountType * @var{type})
-Converts a string of the form returned by @code{xaccAccountTypeEnumAsString}
-to a type, return in @var{type}. Returns true if the string corresponds
-to an actual type.
- at end deftypefun
-
- at deftypefun GNCAccountType xaccAccountStringToEnum (const char * @var{str})
-Similar to @code{xaccAccountStringToEnum}, but returns the type. If
- at var{str} does not correspond to any valid type, @code{BAD_TYPE} is
-returned.
- at end deftypefun
-
- at deftypefun gboolean xaccAccountTypesCompatible (GNCAccountType @var{parent_type}, GNCAccountType @var{child_type})
-Returns TRUE if accounts of type @var{parent_type} can have child accounts
-of type @var{child_type}. This compatibility is not enforced by the
-engine, but one day it may be!
- at end deftypefun
-
-
- at node Account Getters, Account Tax API, Account Type API, Accounts
- at subsection Account Getters
-
- at deftypefun GNCAccountType xaccAccountGetType (Account * @var{account})
-Return the type of @var{account}.
- at end deftypefun
-
- at deftypefun {const char *} xaccAccountGetName (Account * @var{account})
-Return the name of @var{account}.
- at end deftypefun
-
- at deftypefun {const char *} xaccAccountGetCode (Account * @var{account})
-Return the code of @var{account}.
- at end deftypefun
-
- at deftypefun {const char *} xaccAccountGetDescription (Account * @var{account})
-Return the description of @var{account}.
- at end deftypefun
-
- at deftypefun {const char *} xaccAccountGetNotes (Account * @var{account})
-Return the notes of @var{account}.
- at end deftypefun
-
- at deftypefun {gnc_commodity *} xaccAccountGetCurrency (Account * @var{account})
-Return the currency of @var{account}.
- at end deftypefun
-
- at deftypefun int xaccAccountGetCurrencySCU (Account * @var{account})
-Return the SCU (smallest convertible unit) of @var{account}'s
-currency.
- at end deftypefun
-
- at deftypefun {gnc_commodity *} xaccAccountGetSecurity (Account * @var{account})
-Return the security of @var{account}. For accounts without shares, this
-field will be @code{NULL}.
- at end deftypefun
-
- at deftypefun int xaccAccountGetSecuritySCU (Account * @var{account})
-Return the SCU (smallest convertible unit) of @var{account}'s
-security.
- at end deftypefun
-
- at deftypefun {gnc_commodity *} xaccAccountGetEffectiveSecurity (Account * @var{account})
-Get the `effective' security of the account. If the account has a non-NULL
-security field, that field will be returned. Otherwise, the currency will
-be returned.
- at end deftypefun
-
- at deftypefun {AccountGroup *} xaccAccountGetChildren (Account * @var{account})
-Return the child group of @var{account}. The child group may be @code{NULL},
-indicating @var{account} has no children.
- at end deftypefun
-
- at deftypefun {AccountGroup *} xaccAccountGetParent (Account * @var{account})
-Return the parent Group of @var{account}. The parent may be @code{NULL},
-indicating @var{account} is a top-level Account. However, even if the
-parent is not @code{NULL}, the account may still be top-level if the
-parent Group has no parent Account.
- at end deftypefun
-
- at deftypefun {Account *} xaccAccountGetParentAccount (Account * @var{account})
-Similar to @code{xaccAccountGetParent}, but returns the parent Account
-of the parent Group if the parent Group exists. Otherwise, returns
- at code{NULL}.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetBalance (Account * @var{account})
-Return the balance of @var{account}, which is also the balance of the
-last Split in @var{account}. If there are no Splits, the balance is
-zero. The balance is denominated in the Account currency.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetClearedBalance (Account * @var{account})
-Return the cleared balance of @var{account}. The cleared balance is the
-balance of all Splits in @var{account} which are either cleared or
-reconciled or frozen. The cleared balance is denominated in the Account
-currency.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetReconciledBalance (Account * @var{account})
-Return the reconciled balance of @var{account}. The reconciled balance
-is the balance of all Splits in @var{account} which are reconciled or
-frozen. The reconciled balance is denominated in the Account currency.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetShareBalance (Account *account)
-Return the share balance of @var{account}, which is also the share
-balance of the last Split in @var{account}. If there are no Splits, the
-balance is zero. The balance is denominated in the Account security, if
-the Account security exits; otherwise the share balance is denominated
-in the Account currency.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetShareClearedBalance (Account * @var{account})
-Return the cleared share balance of @var{account}. The cleared share
-balance is the share balance of all Splits in @var{account} which are
-either cleared or reconciled or frozen. The cleared share balance is
-denominated as the share balance.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetShareReconciledBalance (Account * @var{account})
-Return the reconciled share balance of @var{account}. The reconciled
-share balance is the share balance of all Splits in @var{account} which
-are reconciled or frozen. The reconciled sharea balance is denominated
-as the share balance.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetBalanceAsOfDate (Account * @var{account}, time_t @var{date})
-Return the balance of @var{account} including all Splits whose parent
-Transactions have posted dates on or before @var{date}.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetShareBalanceAsOfDate (Account * @var{account}, time_t @var{date})
-Return the share balance of @var{account} including all Splits whose
-parent Transactions have posted dates on or before @var{date}.
- at end deftypefun
-
- at deftypefun {GList *} xaccAccountGetSplitList (Account * @var{account})
-Return a @code{GList} of the Splits in @var{account}. This list must
-not be modified in any way.
- at end deftypefun
-
- at deftypefun {char *} xaccAccountGetFullName (Account * @var{account}, const char @var{separator})
-Returns the fully qualified name of @var{account} using the given
-separator character. The name must be g_freed after use. The fully
-qualified name of an account is the concatenation of the names of the
-account and all its ancestor accounts starting with the topmost account
-and ending with the given account. Each name is separated by the given
-character.
- at end deftypefun
-
-
- at node Account Tax API, , Account Getters, Accounts
- at subsection Account Tax API
-
-This set of API calls is related to tax information. All accounts have a
-tax-related boolean flag that can be set or unset. There is an
-additional set of API calls related to United States taxes that have
-`US' in the function call names. Future API calls that are specific to
-other countries should include the appropriate 2-letter country code in
-the function names.
-
- at deftypefun gboolean xaccAccountGetTaxRelated (Account * @var{account})
-Return the tax-related flag of @var{account}.
- at end deftypefun
-
- at deftypefun void xaccAccountSetTaxRelated (Account * @var{account}, gboolean @var{tax_related})
-Set the tax-related flag of @var{account}.
- at end deftypefun
-
- at deftypefun {const char *} xaccAccountGetTaxUSCode (Account * @var{account})
-Get the US-specific tax code associated with @var{account}, or
- at code{NULL} if there is none. These codes are internal to GnuCash
-and currently defined in @file{src/scm/report/txf-export.scm}.
- at end deftypefun
-
- at deftypefun void xaccAccountSetTaxUSCode (Account * @var{account}, const char * @var{code})
-Set the US-specific tax code associated with @var{account}.
- at end deftypefun
-
- at deftypefun {const char *} xaccAccountGetTaxUSPayerNameSource (Account * @var{account})
-Get the payer name source associated with @var{account}. See
- at file{src/scm/repot/taxtxf.scm} for details.
- at end deftypefun
-
- at deftypefun void xaccAccountSetTaxUSPayerNameSource (Account * @var{account}, const char * @var{source})
-Set the payer name source associated with @var{account}.
- at end deftypefun
-
-
- at node Account Groups, GNCBooks, Accounts, Engine
- at section Account Groups
- at tindex AccountGroup
-
-Account Groups are used by the Engine to connect Accounts
-together into an Account hierarchy. Account Groups do not
-correspond to any accounting concept -- they are specific
-to the GnuCash engine. Account Groups contain the following
-pieces of information:
-
- at table @asis
-
- at item A list of Accounts
-The list Accounts in the Group.
-
- at item A not-saved flag
-Indicates whether any information in the hierarchy
-rooted at the Group needs to be saved. That includes
-Accounts, Splits, and Transactions.
-
- at end table
-
-Account Groups do not have key-value frames or GUIDs.
-
- at menu
-* General Account Group API::
-* Account Group Account API::
- at end menu
-
- at node General Account Group API, Account Group Account API, Account Groups, Account Groups
- at subsection General Account Group API
-
- at deftypefun {AccountGroup *} xaccMallocAccountGroup (void)
-Return a newly-allocated & initialized Account Group.
-The Group must be freed with @code{xaccFreeAccountGroup}.
- at end deftypefun
-
- at deftypefun void xaccFreeAccountGroup (AccountGroup * @var{account_group})
-Free the given Group and all its resources, including the Accounts.
- at end deftypefun
-
- at deftypefun void xaccAccountGroupCommitEdit (AccountGroup * @var{grp})
-Recursively call @code{xaccAccountCommitEdit} on all child accounts
-and their children.
- at end deftypefun
-
- at deftypefun void xaccGroupConcatGroup (AccountGroup * @var{to}, AccountGroup * @var{from})
-Move all accounts in @var{from} to @var{to}. After this function
-returns, @var{from} will have been destroyed.
- at end deftypefun
-
- at deftypefun void xaccGroupMergeAccounts (AccountGroup * @var{grp})
-Merge all accounts in @var{grp} that have the same name and description.
-The semantics of this function are rather complex. Consult the
-implementation before use!
- at end deftypefun
-
- at deftypefun gboolean xaccGroupNotSaved (AccountGroup * @var{grp})
-Return true if @var{grp} has changes which have not been saved.
- at end deftypefun
-
- at deftypefun void xaccGroupMarkSaved (AccountGroup * @var{grp})
-Mark @var{grp} and all its children as saved.
- at end deftypefun
-
- at deftypefun void xaccGroupMarkNotSaved (AccountGroup * @var{grp})
-Mark @var{grp} as not saved.
- at end deftypefun
-
- at deftypefun void xaccGroupMarkDoFree (AccountGroup * @var{grp})
-Mark all accounts in @var{grp} as slated for destruction. This will
-improve the efficiency of destroying a large account hierarchy.
- at end deftypefun
-
-
- at node Account Group Account API, , General Account Group API, Account Groups
- at subsection Account Group Account API
-
- at deftypefun void xaccGroupRemoveAccount (AccountGroup * @var{grp}, Account * @var{account})
-Remove @var{account} from @var{grp}. If @var{account} is not in
- at var{grp}, the function will return without performing any action.
-In no case will @var{account} be destroyed or modified.
- at end deftypefun
-
- at deftypefun void xaccAccountRemoveGroup (Account * @var{acc})
-Remove @var{acc}'s child group. The child group is not otherwise
-modified or destroyed.
- at end deftypefun
-
- at deftypefun void xaccGroupInsertAccount (AccountGroup * @var{grp}, Account * @var{acc})
-Add @var{acc} to @var{grp}. If @var{acc} is in another Group, it will be
-removed first.
- at end deftypefun
-
- at deftypefun void xaccAccountInsertSubAccount (Account * @var{parent}, Account * @var{child})
-Like @code{xaccGroupInsertAccount}, but uses a parent Account instead
-of a parent group. If @var{parent} does not have a child Group, one
-will be created.
- at end deftypefun
-
- at deftypefun int xaccGroupGetNumSubAccounts (AccountGroup * @var{grp})
-Return the total number of Accounts in the hierarchy rooted at @var{grp}.
- at end deftypefun
-
- at deftypefun int xaccGroupGetNumAccounts (AccountGroup * @var{grp})
-Return the number of accounts in @var{grp}. This count does not
-include Accounts lower in the hierarchy.
- at end deftypefun
-
- at deftypefun int xaccGroupGetDepth (AccountGroup * @var{grp})
-Returns the length of the longest tree branch in the hierarchy
-rooted at @var{grp}. Each link between an Account and its
-(non-null) children counts as one unit of length.
- at end deftypefun
-
- at deftypefun {Account *} xaccGroupGetAccount (AccountGroup * @var{group}, int @var{index})
-Return the @var{index}th Account in @var{group}, starting at zero.
-If @var{index} is out of range, @code{NULL} is returned.
- at end deftypefun
-
- at deftypefun {GList *} xaccGroupGetSubAccounts (AccountGroup * @var{grp})
-Return a list of the Accounts, including sub-Accounts, in @var{grp}. The
-returned list should be freed with @code{g_list_free} when no longer
-needed.
- at end deftypefun
-
- at deftypefun {GList *} xaccGroupGetAccountList (AccountGroup * @var{grp})
-Return a list of the immediate children of @var{grp}. The returned list
-should not be freed or modified in any way.
- at end deftypefun
-
-
- at node GNCBooks, Scrub, Account Groups, Engine
- at section GNCBooks
- at tindex GNCBook
-
-The @dfn{GNCBook} interface encapsulates all the information about a
-GnuCash dataset, including the methods used to read and write the
-dataset to datastores. This class provides several important services:
-
- at itemize
-
- at item
-Prevents multiple users from editing the same file at the same time,
-thus avoiding lost data due to race conditions. Thus an 'open book'
-implies that the associated file is locked.
-
- at item
-Provides a search path for the file to be edited. This should simplify
-install & maintenance problems for users who may not have a good grasp
-of what a file system is, or where they want to keep their data files.
-
- at end itemize
-
-The current implementation assumes the use of files and file locks;
-however, the API was designed to be general enough to allow the use
-of generic URL's, and/or implementation on top of SQL or other
-database/persistent object technology.
-
- at menu
-* GNCBook API::
- at end menu
-
-
- at node GNCBook API, , GNCBooks, GNCBooks
- at subsection GNCBook API
-
- at deftypefun {GNCBook *} gnc_book_new (void)
-Allocate, initialize, and return a new GNCBook. The new book will contain
-a newly allocated AccountGroup.
- at end deftypefun
-
- at deftypefun void gnc_book_destroy (GNCBook * @var{book})
-End any editing session associated with @var{book}, and free all
-memory associated with it.
- at end deftypefun
-
- at deftypefun gboolean gnc_book_begin (GNCBook * @var{book}, const char * @var{book_id}, gboolean ignore_lock, gboolean create_if_nonexistent)
-Begins a new book editing session. It takes as an argument the book id.
-The book id must be a string in the form of a URI/URL. In the current
-implementation, only one type of URI is supported, and that is the file
-URI: anything of the form @url{file:/home/somewhere/somedir/file.xac}
-The path part must be a valid path. The file-part must be a valid
-GnuCash data file. Paths may be relative or absolute. If the path is
-relative; that is, if the argument is @url{file:somefile.xac} then a
-sequence of search paths are checked for a file of this name.
-
-The 'ignore_lock' argument, if set to TRUE, will cause this routine to
-ignore any file locks that it finds. If set to FALSE, then file locks
-will be tested and obeyed.
-
-If the file exists, can be opened and read, and a lock can be obtained
-then a lock will be obtained and the function returns TRUE.
-
-If the file/database doesn't exist, and the create_if_nonexistent flag
-is set to TRUE, then the database is created.
-
-Otherwise the function returns FALSE.
- at end deftypefun
-
- at deftypefun gboolean gnc_book_load (GNCBook * @var{book})
-Load the data associated with the book. The function returns TRUE on
-success.
- at end deftypefun
-
- at deftypefun GNCBackendError gnc_book_get_error (GNCBook * @var{book})
-Obtain the reason for a failure. Standard errno values are used. Calling
-this routine resets the error value. This routine allows an
-implementation of multiple error values, e.g. in a stack, where this
-routine pops the top value. The current implementation has a stack that
-is one-deep.
-
-Some important error values:
-
- at table @code
-
- at item EINVAL
-bad argument
-
- at item ETXTBSY
-book id is in use; it's locked by someone else
-
- at item ENOSYS
-unsupported URI type
-
- at item ERANGE
-file path too long
-
- at item ENOLCK
-book not open when @code{gnc_book_save()} was called.
-
- at end table
- at end deftypefun
-
- at deftypefun {const char *} gnc_book_get_error_message (GNCBook * @var{book})
-Return a string describing the reason for the current error. Calling
-this routine resets the error value.
- at end deftypefun
-
- at deftypefun GNCBackendError gnc_book_pop_error (GNCBook * @var{book})
-Same as @code{gnc_book_get_error}, but the error value is reset
-in @var{book}.
- at end deftypefun
-
- at deftypefun {AccountGroup *} gnc_book_get_group (GNCBook * @var{book})
-Return the current top-level account group.
- at end deftypefun
-
- at deftypefun void gnc_book_set_group (GNCBook * @var{book}, AccountGroup * @var{topgroup})
-Set the topgroup to a new value.
- at end deftypefun
-
- at deftypefun {const char *} gnc_book_get_file_path (GNCBook * @var{book})
-Return the fully-qualified file path for the book. That is, if a
-relative or partial filename was for the book, then it had to have been
-fully resolved to open the book. This routine returns the result of this
-resolution.
- at end deftypefun
-
- at deftypefun gboolean gnc_book_save_may_clobber_data (GNCBook * @var{book})
-Return TRUE if saving the book would overwrite other information.
- at end deftypefun
-
- at deftypefun void gnc_book_save (GNCBook * @var{book})
-Commit all changes that have been made to the book.
- at end deftypefun
-
- at deftypefun void gnc_book_end (GNCBook * @var{book})
-Release the session lock. It will @emph{not} save the account group to
-a file. Thus, this method acts as an "abort" or "rollback" primitive.
- at end deftypefun
-
-
- at node Scrub, , GNCBooks, Engine
- at section Scrub
diff --git a/libgnucash/doc/design/fdl.texi b/libgnucash/doc/design/fdl.texi
deleted file mode 100644
index beeb6666fe..0000000000
--- a/libgnucash/doc/design/fdl.texi
+++ /dev/null
@@ -1,384 +0,0 @@
- at node GNU Free Documentation License, Introduction, Top, Top
- at unnumbered GNU Free Documentation License
-
- at c This file is intended to be included in another file.
-
- at center Version 1.1, March 2000
-
- at display
-Copyright (C) 2000 Free Software Foundation, Inc.
-51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
- at end display
-
- at unnumberedsec Preamble
-
-The purpose of this License is to make a manual, textbook, or other
-written document ``free'' in the sense of freedom: to assure everyone
-the effective freedom to copy and redistribute it, with or without
-modifying it, either commercially or noncommercially. Secondarily,
-this License preserves for the author and publisher a way to get
-credit for their work, while not being considered responsible for
-modifications made by others.
-
-This License is a kind of ``copyleft'', which means that derivative
-works of the document must themselves be free in the same sense. It
-complements the GNU General Public License, which is a copyleft
-license designed for free software.
-
-We have designed this License in order to use it for manuals for free
-software, because free software needs free documentation: a free
-program should come with manuals providing the same freedoms that the
-software does. But this License is not limited to software manuals;
-it can be used for any textual work, regardless of subject matter or
-whether it is published as a printed book. We recommend this License
-principally for works whose purpose is instruction or reference.
-
- at unnumberedsec APPLICABILITY AND DEFINITIONS
-
-This License applies to any manual or other work that contains a
-notice placed by the copyright holder saying it can be distributed
-under the terms of this License. The ``Document'', below, refers to any
-such manual or work. Any member of the public is a licensee, and is
-addressed as ``you''.
-
-A ``Modified Version'' of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-A ``Secondary Section'' is a named appendix or a front-matter section of
-the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document's overall subject
-(or to related matters) and contains nothing that could fall directly
-within that overall subject. (For example, if the Document is in part a
-textbook of mathematics, a Secondary Section may not explain any
-mathematics.) The relationship could be a matter of historical
-connection with the subject or with related matters, or of legal,
-commercial, philosophical, ethical or political position regarding
-them.
-
-The ``Invariant Sections'' are certain Secondary Sections whose titles
-are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License.
-
-The ``Cover Texts'' are certain short passages of text that are listed,
-as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License.
-
-A ``Transparent'' copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the
-general public, whose contents can be viewed and edited directly and
-straightforwardly with generic text editors or (for images composed of
-pixels) generic paint programs or (for drawings) some widely available
-drawing editor, and that is suitable for input to text formatters or
-for automatic translation to a variety of formats suitable for input
-to text formatters. A copy made in an otherwise Transparent file
-format whose markup has been designed to thwart or discourage
-subsequent modification by readers is not Transparent. A copy that is
-not ``Transparent" is called "Opaque''.
-
-Examples of suitable formats for Transparent copies include plain
-ASCII without markup, Texinfo input format, LaTeX input format, SGML
-or XML using a publicly available DTD, and standard-conforming simple
-HTML designed for human modification. Opaque formats include
-PostScript, PDF, proprietary formats that can be read and edited only
-by proprietary word processors, SGML or XML for which the DTD and/or
-processing tools are not generally available, and the
-machine-generated HTML produced by some word processors for output
-purposes only.
-
-The ``Title Page'' means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page. For works in
-formats which do not have any title page as such, ``Title Page'' means
-the text near the most prominent appearance of the work's title,
-preceding the beginning of the body of the text.
-
- at unnumberedsec VERBATIM COPYING
-
-You may copy and distribute the Document in any medium, either
-commercially or noncommercially, provided that this License, the
-copyright notices, and the license notice saying this License applies
-to the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License. You may not use
-technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute. However, you may accept
-compensation in exchange for copies. If you distribute a large enough
-number of copies you must also follow the conditions in section 3.
-
-You may also lend copies, under the same conditions stated above, and
-you may publicly display copies.
-
- at unnumberedsec COPYING IN QUANTITY
-
-If you publish printed copies of the Document numbering more than 100,
-and the Document's license notice requires Cover Texts, you must enclose
-the copies in covers that carry, clearly and legibly, all these Cover
-Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
-the back cover. Both covers must also clearly and legibly identify
-you as the publisher of these copies. The front cover must present
-the full title with all words of the title equally prominent and
-visible. You may add other material on the covers in addition.
-Copying with changes limited to the covers, as long as they preserve
-the title of the Document and satisfy these conditions, can be treated
-as verbatim copying in other respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit
-reasonably) on the actual cover, and continue the rest onto adjacent
-pages.
-
-If you publish or distribute Opaque copies of the Document numbering
-more than 100, you must either include a machine-readable Transparent
-copy along with each Opaque copy, or state in or with each Opaque copy
-a publicly-accessible computer-network location containing a complete
-Transparent copy of the Document, free of added material, which the
-general network-using public has access to download anonymously at no
-charge using public-standard network protocols. If you use the latter
-option, you must take reasonably prudent steps, when you begin
-distribution of Opaque copies in quantity, to ensure that this
-Transparent copy will remain thus accessible at the stated location
-until at least one year after the last time you distribute an Opaque
-copy (directly or through your agents or retailers) of that edition to
-the public.
-
-It is requested, but not required, that you contact the authors of the
-Document well before redistributing any large number of copies, to give
-them a chance to provide you with an updated version of the Document.
-
- at unnumberedsec MODIFICATIONS
-
-You may copy and distribute a Modified Version of the Document under
-the conditions of sections 2 and 3 above, provided that you release
-the Modified Version under precisely this License, with the Modified
-Version filling the role of the Document, thus licensing distribution
-and modification of the Modified Version to whoever possesses a copy
-of it. In addition, you must do these things in the Modified Version:
-
- at enumerate A
- at item
-Use in the Title Page (and on the covers, if any) a title distinct
-from that of the Document, and from those of previous versions
-(which should, if there were any, be listed in the History section
-of the Document). You may use the same title as a previous version
-if the original publisher of that version gives permission.
-
- at item
- List on the Title Page, as authors, one or more persons or entities
-responsible for authorship of the modifications in the Modified
-Version, together with at least five of the principal authors of the
-Document (all of its principal authors, if it has less than five).
-
- at item
-State on the Title page the name of the publisher of the
-Modified Version, as the publisher.
-
- at item
- Preserve all the copyright notices of the Document.
-
- at item
-Add an appropriate copyright notice for your modifications
-adjacent to the other copyright notices.
-
- at item
-Include, immediately after the copyright notices, a license notice
-giving the public permission to use the Modified Version under the
-terms of this License, in the form shown in the Addendum below.
-
- at item
-Preserve in that license notice the full lists of Invariant Sections
-and required Cover Texts given in the Document's license notice.
-
- at item
-Include an unaltered copy of this License.
-
- at item
-Preserve the section entitled ``History'', and its title, and add to
-it an item stating at least the title, year, new authors, and
-publisher of the Modified Version as given on the Title Page. If
-there is no section entitled ``History'' in the Document, create one
-stating the title, year, authors, and publisher of the Document as
-given on its Title Page, then add an item describing the Modified
-Version as stated in the previous sentence.
-
- at item
-Preserve the network location, if any, given in the Document for
-public access to a Transparent copy of the Document, and likewise
-the network locations given in the Document for previous versions
-it was based on. These may be placed in the ``History'' section.
-You may omit a network location for a work that was published at
-least four years before the Document itself, or if the original
-publisher of the version it refers to gives permission.
-
- at item
-In any section entitled ``Acknowledgements" or "Dedications'',
-preserve the section's title, and preserve in the section all the
-substance and tone of each of the contributor acknowledgements
-and/or dedications given therein.
-
- at item
-Preserve all the Invariant Sections of the Document,
-unaltered in their text and in their titles. Section numbers
-or the equivalent are not considered part of the section titles.
-
- at item
-Delete any section entitled ``Endorsements''. Such a section
-may not be included in the Modified Version.
-
- at item
-Do not retitle any existing section as ``Endorsements''
-or to conflict in title with any Invariant Section.
- at end enumerate
-
-If the Modified Version includes new front-matter sections or
-appendices that qualify as Secondary Sections and contain no material
-copied from the Document, you may at your option designate some or all
-of these sections as invariant. To do this, add their titles to the
-list of Invariant Sections in the Modified Version's license notice.
-These titles must be distinct from any other section titles.
-
-You may add a section entitled ``Endorsements'', provided it contains
-nothing but endorsements of your Modified Version by various
-parties--for example, statements of peer review or that the text has
-been approved by an organization as the authoritative definition of a
-standard.
-
-You may add a passage of up to five words as a Front-Cover Text, and a
-passage of up to 25 words as a Back-Cover Text, to the end of the list
-of Cover Texts in the Modified Version. Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or
-through arrangements made by) any one entity. If the Document already
-includes a cover text for the same cover, previously added by you or
-by arrangement made by the same entity you are acting on behalf of,
-you may not add another; but you may replace the old one, on explicit
-permission from the previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this License
-give permission to use their names for publicity for or to assert or
-imply endorsement of any Modified Version.
-
- at unnumberedsec COMBINING DOCUMENTS
-
-You may combine the Document with other documents released under this
-License, under the terms defined in section 4 above for modified
-versions, provided that you include in the combination all of the
-Invariant Sections of all of the original documents, unmodified, and
-list them all as Invariant Sections of your combined work in its
-license notice.
-
-The combined work need only contain one copy of this License, and
-multiple identical Invariant Sections may be replaced with a single
-copy. If there are multiple Invariant Sections with the same name but
-different contents, make the title of each such section unique by
-adding at the end of it, in parentheses, the name of the original
-author or publisher of that section if known, or else a unique number.
-Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections entitled ``History''
-in the various original documents, forming one section entitled
-``History"; likewise combine any sections entitled "Acknowledgements'',
-and any sections entitled ``Dedications''. You must delete all sections
-entitled ``Endorsements.''
-
- at unnumberedsec COLLECTIONS OF DOCUMENTS
-
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this
-License in the various documents with a single copy that is included in
-the collection, provided that you follow the rules of this License for
-verbatim copying of each of the documents in all other respects.
-
-You may extract a single document from such a collection, and distribute
-it individually under this License, provided you insert a copy of this
-License into the extracted document, and follow this License in all
-other respects regarding verbatim copying of that document.
-
- at unnumberedsec AGGREGATION WITH INDEPENDENT WORKS
-
-A compilation of the Document or its derivatives with other separate
-and independent documents or works, in or on a volume of a storage or
-distribution medium, does not as a whole count as a Modified Version
-of the Document, provided no compilation copyright is claimed for the
-compilation. Such a compilation is called an ``aggregate'', and this
-License does not apply to the other self-contained works thus compiled
-with the Document, on account of their being thus compiled, if they
-are not themselves derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one quarter
-of the entire aggregate, the Document's Cover Texts may be placed on
-covers that surround only the Document within the aggregate.
-Otherwise they must appear on covers around the whole aggregate.
-
- at unnumberedsec TRANSLATION
-
-Translation is considered a kind of modification, so you may
-distribute translations of the Document under the terms of section 4.
-Replacing Invariant Sections with translations requires special
-permission from their copyright holders, but you may include
-translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections. You may include a
-translation of this License provided that you also include the
-original English version of this License. In case of a disagreement
-between the translation and the original English version of this
-License, the original English version will prevail.
-
- at unnumberedsec TERMINATION
-
-You may not copy, modify, sublicense, or distribute the Document except
-as expressly provided for under this License. Any other attempt to
-copy, modify, sublicense or distribute the Document is void, and will
-automatically terminate your rights under this License. However,
-parties who have received copies, or rights, from you under this
-License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
- at unnumberedsec FUTURE REVISIONS OF THIS LICENSE
-
-The Free Software Foundation may publish new, revised versions
-of the GNU Free Documentation License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns. See
-https://www.gnu.org/copyleft/.
-
-Each version of the License is given a distinguishing version number.
-If the Document specifies that a particular numbered version of this
-License ``or any later version'' applies to it, you have the option of
-following the terms and conditions either of that specified version or
-of any later version that has been published (not as a draft) by the
-Free Software Foundation. If the Document does not specify a version
-number of this License, you may choose any version ever published (not
-as a draft) by the Free Software Foundation.
-
-
-
- at unnumberedsec ADDENDUM: How to use this License for your documents
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and
-license notices just after the title page:
-
- at display
-Copyright (c) YEAR YOUR NAME.
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1
-or any later version published by the Free Software Foundation;
-with the Invariant Sections being LIST THEIR TITLES, with the
-Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
-A copy of the license is included in the section entitled "GNU
-Free Documentation License".
- at end display
-
-If you have no Invariant Sections, write ``with no Invariant Sections''
-instead of saying which ones are invariant. If you have no
-Front-Cover Texts, write ``no Front-Cover Texts'' instead of
-``Front-Cover Texts being LIST''; likewise for Back-Cover Texts.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License,
-to permit their use in free software.
-
- at c @bye
diff --git a/libgnucash/doc/design/function-index.texi b/libgnucash/doc/design/function-index.texi
deleted file mode 100644
index 3dec20bf07..0000000000
--- a/libgnucash/doc/design/function-index.texi
+++ /dev/null
@@ -1,4 +0,0 @@
- at node Function Index, Data Type Index, User Preferences, Top
- at unnumbered Function Index
-
- at printindex fn
diff --git a/libgnucash/doc/design/gnucash-design.texi b/libgnucash/doc/design/gnucash-design.texi
deleted file mode 100644
index 2bfc24b6f7..0000000000
--- a/libgnucash/doc/design/gnucash-design.texi
+++ /dev/null
@@ -1,239 +0,0 @@
-\input texinfo @c -*-texinfo-*-
- at c %**start of header
- at setfilename gnucash-design.info
- at settitle GnuCash Design Document
- at c %**end of header
-
- at comment 'version.texi' is a magic filename that, when included,
- at comment will be auto-generated courtesy of automake.
- at include version.texi
-
- at ifinfo
- at format
-
- at dircategory Programming
-
- at direntry
-* gnucash: (gnucash-design). Design of the GnuCash program
- at end direntry
-
- at end format
- at end ifinfo
-
- at ifinfo
-This file documents the design of the GnuCash program.
-
-Copyright 2000 Gnumatic Incorporated
-
-This is Edition @value{EDITION}, last updated @value{UPDATED},
-of the @cite{GnuCash Design Document}, version @value{VERSION}.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1
-or any later version published by the Free Software Foundation;
-with the Invariant Sections being LIST THEIR TITLES, with the
-Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
-A copy of the license is included in the section entitled "GNU
-Free Documentation License".
-
- at ignore
-Permission is granted to process this file through TeX
-and print the results, provided the printed document
-carries a copying permission notice identical to this
-one except for the removal of this paragraph (this
-paragraph not being relevant to the printed manual).
- at end ignore
-
- at end ifinfo
-
- at titlepage
- at title GnuCash Design Document
- at subtitle Edition @value{EDITION} for Version @value{VERSION}
- at author Rob Browning
- at author Bill Gribble
- at author Robert Merkel
- at author Dave Peticolas
- at author Linas Vepstas
- at page
- at vskip 0pt plus 1filll
- at copyright{} 2000 Gnumatic Incorporated
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1
-or any later version published by the Free Software Foundation;
-with the Invariant Sections being LIST THEIR TITLES, with the
-Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
-A copy of the license is included in the section entitled "GNU
-Free Documentation License".
- at end titlepage
-
- at ifnottex
- at node Top, GNU Free Documentation License, (dir), (dir)
- at top GnuCash Design Document
-This is Edition @value{EDITION}, last updated @value{UPDATED},
-of the @cite{GnuCash Design Document}, version @value{VERSION}.
- at end ifnottex
-
- at menu
-* GNU Free Documentation License::
-* Introduction::
-* Top Level::
-* Engine::
-* Component Manager::
-* Register::
-* Reports::
-* User Preferences::
-* Function Index::
-* Data Type Index::
-* Concept Index::
-
-
- at detailmenu
- --- The Detailed Node Listing ---
-
-Engine
-
-* Engine Introduction::
-* Using and Extending the Engine API::
-* Globally Unique Identifiers::
-* Numeric Library::
-* Key-Value Pair Frames::
-* Events::
-* Commodities::
-* Commodity Tables::
-* Prices::
-* Price Databases::
-* Splits::
-* Transactions::
-* Accounts::
-* Account Groups::
-* GNCBooks::
-* Scrub::
-
-Globally Unique Identifiers
-
-* When to use GUIDs::
-* GUID Types::
-* How to use GUIDs::
-* GUIDs and GnuCash Entities::
-* The GUID Generator::
-
-Numeric Library
-
-* Standard Numeric Arguments::
-* Creating Numeric Objects::
-* Basic Arithmetic Operations::
-* Numeric Comparisons and Predicates::
-* Numeric Denominator Conversion::
-* Numeric Floating Point Conversion::
-* Numeric String Conversion::
-* Numeric Error Handling ::
-* Numeric Example::
-
-Key-Value Pair Frames
-
-* Key-Value Policy::
-* kvp_frame::
-* KvpValue::
-* kvp_list::
-
-Events
-
-* Event API::
-
-Commodities
-
-* General Commodity API::
-* Commodity Getters::
-* Commodity Setters::
-
-Commodity Tables
-
-* General Commodity Table API::
-* Commodity Table Access API::
-* Commodity Table Modification API::
-
-Prices
-
-* Price Implementation Details::
-* General Price API::
-* Price Getters::
-* Price Setters::
-
-Price Databases
-
-* Price Lists::
-* General Price Database API::
-
-Splits
-
-* General Split API::
-* Split Getters::
-* Split Setters::
-
-Transactions
-
-* General Transaction API::
-* Transaction Getters::
-* Transaction Setters::
-
-Accounts
-
-* Account Types::
-* General Account API::
-* Account Type API::
-* Account Getters::
-
-Account Groups
-
-* General Account Group API::
-* Account Group Account API::
-
-GNCBooks
-
-* GNCBook API::
-
-Component Manager
-
-* Component Manager Introduction::
-
-Register
-
-* Cells::
-* Cellblocks::
-* Table::
-* Split Register::
-
-Cells
-
-* BasicCell::
-
-Reports
-
-* Creating a Report::
-
-User Preferences
-
-* Option Databases::
-* Option Types::
-* Option Creation::
-* Option Values::
-
- at end detailmenu
- at end menu
-
- at include fdl.texi
- at include intro.texi
- at include top-level.texi
- at include engine.texi
- at include component-manager.texi
- at include register.texi
- at include reports.texi
- at include user-preferences.texi
- at include function-index.texi
- at include type-index.texi
- at include concept-index.texi
-
- at summarycontents
- at contents
-
- at bye
diff --git a/libgnucash/doc/design/intro.texi b/libgnucash/doc/design/intro.texi
deleted file mode 100644
index be292e636f..0000000000
--- a/libgnucash/doc/design/intro.texi
+++ /dev/null
@@ -1,49 +0,0 @@
- at node Introduction, Top Level, GNU Free Documentation License, Top
- at unnumbered Introduction
-
- at strong{This whole document is completely outdated. Don't read this. All
-function names and every described structure has changed
-completely. Only read this if you want to know how gnucash looked like
-in 1999. This is completely outdated!}
-
-This document defines the design and architecture of the GnuCash
-program, an application for tracking finances. GnuCash is composed
-of several subsystems or modules. This document describes each module,
-specifying its interface and, where appropriate, its implementation,
-as well as describing the interactions between each module.
-
- at unnumberedsec Who Should Read This Document?
-
-Anyone who plans on making a significant change or addition to GnuCash's
-functionality should read this document. By adhering to the structure
-presented here, your contribution will be more likely to work correctly
-with existing and future features.
-
- at unnumberedsec Goals
-
-GnuCash is intended to be a finance and accounting program for
-individuals and small businesses. As such, it should have the
-following primary features:
-
- at itemize
-
- at item
-A sound underlying model for financial entities such as currencies,
-transactions, and accounts.
-
- at item
-A user interface which provides an efficient way to accomplish
-common tasks, such as transaction entry, account reconciliation,
-etc.
-
- at item
-The ability to generate and print standard financial reports
-such as Income Statements, Balance Sheets, etc.
-
- at item
-The ability to generate and print graphs of financial information.
-
- at end itemize
-
-A more comprehensive list of current and planned features for GnuCash
-is located at @uref{http://cvs.gnucash.org/linux/gnucash/projects.html}.
diff --git a/libgnucash/doc/design/register.texi b/libgnucash/doc/design/register.texi
deleted file mode 100644
index 9ec2671ad7..0000000000
--- a/libgnucash/doc/design/register.texi
+++ /dev/null
@@ -1,162 +0,0 @@
- at node Register, Reports, Component Manager, Top
- at chapter Register
- at cindex Register
-
- at strong{This whole document is completely outdated. Don't read this. All
-function names and every described structure has changed
-completely. Only read this if you want to know how gnucash looked like
-in 1999. This is completely outdated!}
-
-The register is an infrastructure for building a modular matrix of cells
-in which each cell may be specialized to perform a particular function,
-e.g., to read dates, numerical amounts, or text. The register has been
-designed to be easy to extend, modular, easy to maintain, and memory
-efficient. It is intended to be used for building financial apps and
-spread-sheets.
-
-The register object should not have any 'knowledge' of the accounting
-model of GnuCash or of the workings of the main application. The
-register should not be specific to a particular GUI (such as Gnome/GTK).
-It should be possible to use the register in a stand-alone fashion.
-
-The register is built from several types of components: Cells,
-Cellblocks, Cursors, the Table, and the Split Register.
-
- at menu
-* Cells::
-* Cellblocks::
-* Table::
-* Split Register::
- at end menu
-
-
- at node Cells, Cellblocks, Register, Register
- at section Cells
-
-A @dfn{Cell} is an active object which is designed to read a specific
-kind of user input. A Cell object has callbacks that are called when
-the user enters the cell (e.g. by mouse-clicking on a cell in a table,
-or tabbing into it), when the user attempts to modify text in the cell
-(e.g. by typing in it), and when the user leaves the cell (e.g. by
-mouse-clicking elsewhere, or tabbing away).
-
-Special-purpose cells can be created by "inheriting" from the basic cell
-object. Thus, there are special-purpose cells for handling dates,
-pull-down menus, text fields with auto-completion from a list of
-alternatives, monetary amounts, etc.
-
-Cells implementations may or may not contain GUI code. Cells which
-require only that text be displayed are completely "GUI-independent",
-that is, they depend on the underlying table to display the text. Cells
-which require additional GUI elements (such as pull-down menus) must
-implement the proper GUI handling on their own (using, e.g., GTK).
-
- at menu
-* BasicCell::
- at end menu
-
-
- at node BasicCell, , Cells, Cells
- at subsection BasicCell
- at tindex BasicCell
-
-The @dfn{BasicCell} interface defines the core functionality that all
-cells must implement. A BasicCell contains the following data members.
-
- at table @code
-
- at item char *value
-The 'value' of the cell stored as a character string.
-
- at item GdkWChar *w_value
-The 'value' of the cell stores as a wide character string.
-
- at item gint value_len
-The length of w_value.
-
- at item guint32 changed
-This member is set to have all 1-bits (2^32 - 1) to indicate the
-cell contents have been changed from the register value.
-
- at item guint32 conditionally_changed
-This member is set to have all 1-bits (2^32 - 1) to indicate the
-cell contents have been changed from the register value, but that
-the register should not be considered to be changed unless other
-cells have been changed (not conditionally).
-
- at item char * blank_help
-This member is a text string which may be used by a GUI implementation
-to display an informative help string when the value of a cell is empty
-(perhaps prompting the user to enter a particular kind of value).
-
- at end table
-
-
- at node Cellblocks, Table, Cells, Register
- at section Cellblocks
-
-A @dfn{Cellblock} is an array of active cells. The cells are laid out in
-rows and columns. The cellblock serves as a convenient container for
-organizing active cells in an array. Through the mechanism of Cursors
-(defined below), it allows a group of cells to be treated as a single
-transactional entity. That is, the cursor/cellblock allows all edits to
-a groups of cells to be simultaneously committed or rejected by
-underlying engines. This makes it appropriate for use as a GUI for
-transaction-processing applications with two-phase commit requirements.
-
-
- at node Table, Split Register, Cellblocks, Register
- at section Table
-
-The @dfn{Table} is a displayed matrix. The table is a complex object;
-it is @emph{not} merely a cellblock. The table provides all of the GUI
-infrastructure for displaying a row-column matrix of strings.
-
-The table provides one very important function for minimizing memory
-usage for large matrixes -- the notion of a @dfn{Cursor}. The cursor is
-a cellblock (an array of active cells) that is moved to the location
-that the user is currently editing. The cursor "virtualizes" cell
-functions; that is, it makes it seem to the user as if all cells in the
-table are active, when in fact the only cell that actually needs to be
-active is the one that the user is currently editing.
-
-The table design allows multiple cursors to be defined. When a user
-enters a cell, the appropriate cursor is positioned within the table.
-Cursors cannot overlap: any given cell can be mapped to at most one
-cursor. Multiple-cursor support allows tables to be designed that have a
-non-uniform layout. For example, the multiple-cursor support can be used
-to define a tree structure of headings and sub-headings, where the
-layout/format of the heading is different from the sub-headings. A
-financial example is a table which lists splits underneath their parent
-transaction. This is very different from a checkbook register, where all
-entries are uniform, and can be handled with a single repeated cursor.
-
-Users of the table must provide a TableView object which provides an API
-the table uses to obtain information about the data it is displaying
-such as strings, colors, etc. Thus, the table represents the non-GUI
-portion of the View object in the Model-View-Controller paradigm.
-
-
- at node Split Register, , Table, Register
- at section Split Register
-
-The split register is a special-purpose object aimed at the display
-of financial transactions. It includes cells for the date, prices,
-balances, transfer accounts, etc. The register is where the cells,
-cursor and table get put together into a unified whole. The register
-defines specific, actual layouts and widths of the date, price, etc.
-cells in a table. It includes a table header, and defines more than
-ten specific layouts: bank, credit-card, stock, general journal, etc.
-
-The split register implementation is divided into two components. The
-first component (src/register/splitreg.[ch]) defines the basic structure
-and implementation of a split register, but does not specifically use or
-depend on the other GnuCash modules, including the Engine. Of course,
-this implementation was created with the engine financial structures in
-mind.
-
-The second component (src/SplitLedger.[ch]) implements the full register
-behavior (the Controller in MVC) and makes full use of the Engine
-API. This component is responsible for loading transactions and splits
-into the register, modifying transactions and splits according to user
-input, and accomplishing tasks such as performing automatic completion.
diff --git a/libgnucash/doc/design/reports.texi b/libgnucash/doc/design/reports.texi
deleted file mode 100644
index d766fecd2a..0000000000
--- a/libgnucash/doc/design/reports.texi
+++ /dev/null
@@ -1,95 +0,0 @@
- at node Reports, User Preferences, Register, Top
- at chapter Reports
- at cindex Reports
-
- at strong{This whole document is completely outdated. Don't read this. All
-function names and every described structure has changed
-completely. Only read this if you want to know how gnucash looked like
-in 1999. This is completely outdated!}
-
-The reporting infrastructure is designed facilitate the creation
-of sophisticated reports including tables, graphs, and hyperlinks.
-The infrastructure includes functionality to support the following:
-
- at itemize
-
- at item
-Creation of tables, with headings, subheadings, totals, and subtotals.
-
- at item
-Formatting of dates & numbers.
-
- at item
-Currency conversions.
-
- at item
-Creation of graphs such as pie and bar charts.
-
- at item
-Creation of hyperlinks to other reports and to other GnuCash
-objects such as registers.
-
- at end itemize
-
- at menu
-* Creating a Report::
- at end menu
-
-
- at node Creating a Report, , Reports, Reports
- at section Creating a Report
-
-To define a report, your report must have
-
- at code{(gnc:support <your_report_name>)}
-
-and should have
-
- at code{(gnc:depend "report-utilities.scm")}
-
-as well as
-
- at code{(gnc:depend "report-html.scm")}
-
-if you wish to use the html generation facilities. You should
-avoid creating HTML directly wherever possible.
-
-To autoload your report, you should add the line @code{(gnc:depend
-<your_report_name>)} to the file @file{src/scm/report/report-list.scm}.
-
- at code{(gnc:depend "date-utilities.scm")}
-
-has lots of date-manipulation functions you'll almost certainly need.
-
-To define a report, you call @code{(gnc:define-report)}. This function
-can accept a variable number of arguments, but at the moment four
-distinct arguments are recognised, as in the following from
-the transaction report:
-
- at example
- (gnc:define-report
- 'version 1
- 'name (N_ "Transaction Report")
- 'options-generator trep-options-generator
- 'renderer trep-renderer)
- at end example
-
- at table @code
-
- at item version
-This is the version number of the report, which is currently ignored.
-
- at item name
-This is the name of the report. It should be marked as translatable,
-but the name should be given in untranslated form, hence the use of
- at code{(N_ )}.
-
- at item options-generator
-This should be a function that takes no arguments and returns an options
-structure with the options for the report. The options interface is
-currently not fully documented, but should be.
-
- at item renderer
-This is the function which renders the HTML.
-
- at end table
diff --git a/libgnucash/doc/design/top-level.texi b/libgnucash/doc/design/top-level.texi
deleted file mode 100644
index f8021ef601..0000000000
--- a/libgnucash/doc/design/top-level.texi
+++ /dev/null
@@ -1,168 +0,0 @@
- at node Top Level, Engine, Introduction, Top
- at chapter Architectural Overview
-
- at strong{This whole document is completely outdated. Don't read this. All
-function names and every described structure has changed
-completely. Only read this if you want to know how gnucash looked like
-in 1999. This is completely outdated!}
-
-GnuCash is written primarily in two languages: C and Scheme. The
-engine/server is written in C primarily for speed, portability,
-stability and historical purposes. Much of the day-to-day workhorse code
-is written in Scheme, primarily for its power, expressiveness and ease
-of development. The user interface is Gtk/Gnome, some of it written in
-C, some in scheme, and some with the GUI designer tool Glade
- at uref{glade.pn.org}.
-
-GnuCash is modular, thereby allowing separate individuals
-to maintain, develop and enhance certain modules without
-disturbing the overall development. (Never mind that
-modules help avoid spaghetti code and nasty, ugly hacks).
-The interfaces between modules are documented, and, for the
-most part, stable and unchanging.
-
-GnuCash currently consists of the following modules:
-
-
- at section The Engine
-
-The @dfn{Engine} (located under the @file{src/engine} directory in the
-GnuCash codebase) provides an interface for creating, manipulating, and
-destroying three basic financial entities: Accounts, Transactions (known
-as Journal Entries in accounting practice), and Splits (known as Ledger
-Entries). These three entities are the central data structures of the
-GnuCash financial data model.
-
-The Engine code contains no GUI code whatsoever.
-
- at subsection Query
-
-The @dfn{Query} module (@file{src/engine/Query.*}) provides an interface
-into the engine for finding transactions based on a set of criteria,
-such as description, date posted, account membership, etc. Simple
-queries can be combined using standard boolean operators.
-
- at subsection File I/O
-
-The @dfn{File I/O} module (@file{src/engine/FileIO.*}) provides an
-interface for reading and writing a set of Accounts, Transactions, and
-Splits to a binary file. This module is deprecated.
-
- at subsection XML I/O
-
-The @dfn{XML I/O} module (@file{src/engine/*xml*.*} and
- at file{src/engine/*sixtp*.*}) provides an interface for reading and
-writing the engine information to an XML format.
-
- at subsection Backend
-
-The @dfn{Backend} module (@file{src/engine/Backend*.*}) provides
-hooks to allow different modules to be used for storing and retrieving
-Engine data. There are two backends currently under development, a
-Postgresql backend (@file{src/engine/sql/*}) and an RPC backend
-(@file{src/engine/rpc/*}).
-
-
- at section The Register
-
-The @dfn{Register} (@file{src/register}) implements a ledger-like
-GUI that allows the user to dynamically enter dates, prices, memos
-descriptions, etc. in an intuitive fashion that should be obvious to
-anyone who's used a checkbook register. The code is highly configurable,
-allowing the ledger columns and rows to be laid out in any way, with no
-restrictions on the function, type, and number of columns/rows. For
-example, one can define a ledger with three date fields, one price
-field, and four memo fields in a straightforward fashion. Cell handling
-objects support and automatically validate date entry, memo entry
-(w/auto-completion), prices, combo-boxes (pull-down menus), and
-multi-state check-boxes. Cells can be marked read-write, or
-output-only. Cells can be assigned unique colors. The currently
-active ledger row-block can be highlighted with a unique color.
-
-The register code is completely independent of the engine code, knows
-nothing about accounting or any of the other GnuCash subsystems. It
-can be used in independent projects that have nothing to do with
-accounting.
-
-
- at section Reports
-
-The @dfn{Reports} module (@file{src/scm/report.scm},
- at file{src/scm/reports}) is a scheme (guile) based system to create
-balance sheets, profit & loss statements, etc. by using the engine
-API to fetch and display data formatted in HTML.
-
-For the most part, this module uses the Query API to fetch the engine
-information instead of using the raw engine interface. This design uses
-Queries to extract the data and assemble it into a view-independent
-format. This data is then be converted to HTML reports and/or graphs
-such as bar and pie charts.
-
-
- at section Graphs
-
-The @dfn{Graphs} module implements GUI graphs such as bar and pie
-charts. These graphs can be interactive in that the user can, for
-example, move pie wedges, and 'live' in that the user can click on graph
-subsections to see a detail graph or report of that particular
-subsection.
-
-This module is implemented using the GUPPI library being developed by
-Jon Trowbridge (@url{https://www.gnome.org/guppi}).
-
-
- at section Price Quotes
-
-The @dfn{Price Quotes} module (@file{src/quotes}) is a Perl system to
-fetch stock price data off the Internet and insert it into the GnuCash
-Engine. This module requires the functionality of the Finance::Quote
-module available from CPAN. The Finance::Quote module can fetch
-price quotes from many different sources including Alphavantage
-and several international exchanges and fund companies.
-
-The Finance::Quote module also supports fetching currency exchange
-rates. GnuCash will be extended to allow the fetching and use of
-currency exchange rates.
-
-
- at section User Preferences
-
-The @dfn{User Preferences} module (@file{src/scm/options.scm},
- at file{src/scm/prefs.scm}) provides an infrastructure for defining both
-user-configurable and internal preferences. Preferences are defined in
-scheme using several predefined preference types such as boolean,
-string, date, etc. Preferences are 'implemented' by providing a GUI
-which allows the user to see and change preference values. An API
-is provided to query preference values and to register callbacks
-which will be invoked when preferences change.
-
-Preference values which are different from the default values
-are stored as scheme forms in a user-specific preferences file
-(@file{~/.gnucash/config.auto}). This file is automatically
-loaded upon startup.
-
-
- at section QIF Import
-
-The @dfn{QIF Import} module (@file{src/scm/qif-import}) provides
-functionality for importing QIF (Quicken Interchange Format) data
-into GnuCash.
-
-
- at section GnuCash
-
-The GnuCash module (@file{src/gnome}, @file{src/register/gnome} and
- at file{src/*.[ch]}) is the main GUI application. It consists of a
-collection of miscellaneous GUI code to glue together all of the pieces
-above into a coherent, point-and-click whole. It is meant to be easy to
-use and intuitive to the novice user without sacrificing the power and
-flexibility that a professional might expect. When people say that
-GnuCash is trying to be a "Quicken or MS Money look/work/act-alike",
-this is the piece that they are referring to. It really is meant to
-be a personal-finance manager with enough power for the power user
-and the ease of use for the beginner.
-
-Currently, the Gnome interface is the only operational interface. There
-is an obsolete Motif interface which is not maintained and which is
-removed in current CVS. There is also old Qt code (removed in current
-CVS) which won't compile, and most/all functions are missing.
diff --git a/libgnucash/doc/design/type-index.texi b/libgnucash/doc/design/type-index.texi
deleted file mode 100644
index aa8c05867b..0000000000
--- a/libgnucash/doc/design/type-index.texi
+++ /dev/null
@@ -1,4 +0,0 @@
- at node Data Type Index, Concept Index, Function Index, Top
- at unnumbered Date Type Index
-
- at printindex tp
diff --git a/libgnucash/doc/design/user-preferences.texi b/libgnucash/doc/design/user-preferences.texi
deleted file mode 100644
index 08f066a5a8..0000000000
--- a/libgnucash/doc/design/user-preferences.texi
+++ /dev/null
@@ -1,306 +0,0 @@
- at node User Preferences, Function Index, Reports, Top
- at chapter User Preferences
- at cindex User Preferences
-
- at strong{This whole document is completely outdated. Don't read this. All
-function names and every described structure has changed
-completely. Only read this if you want to know how gnucash looked like
-in 1999. This is completely outdated!}
-
-The options system is used to obtain user preferences, both globally,
-and when displaying a report. A wide variety of option types are
-supported, so it should be possible to create an option for just about
-any property the user might wish to specify. New option types can be
-added if necessary, but as the process requires detailed knowledge of
-GnuCash internals and GTK+/GNOME, it is not documented here.
-
-At present, users are most likely to come across the options system when
-designing custom reports, and are consequently mostly going to use the
-Scheme interface. There is also a C interface to much of the options
-system which is used to access preferences for the UI, but it is not yet
-documented.
-
- at menu
-* Option Databases::
-* Option Types::
-* Option Creation::
-* Option Values::
- at end menu
-
- at node Option Databases, Option Types, User Preferences, User Preferences
- at section Option Databases
- at cindex Option Databases
-
-The options for a particular report are placed in an @dfn{options
-database}. For doing a report, the option-generator function must
-return an options database. The function
-
- at code{(gnc:new-option)}
-
-returns a new, empty options database that you can then add options to.
-
-Options are organised into sections, which are each given a title string
-such as "Register" or "International". The UI displays each section on
-a separate page. Each section has a number of options. Each option has
-a name that uniquely identifies it in that section, and an alphabetic
- at dfn{sort tag} that determines the relative ordering of the options for
-display.
-
- at node Option Types, Option Creation, Option Databases, User Preferences
- at section Option Types
-
-Sometimes, GnuCash requires the user to specify true/false properties.
-Others properties most easily specified by selections from a list,
-others from a number, others still by selecting dates, or one or more
-accounts in the account hierarchy, or even colors. GnuCash supports all
-of these and more:
-
- at table @code
-
- at item boolean
-
-These are displayed as a checkbox by the UI. They are used to specify
-yes/no answers.
-
- at item string
-
-The UI provides a text entry box where arbitrary text may be entered.
-
- at item font
-
-This allows users to select fonts from those available on the system.
-
- at item currency
-
-For specifying a currency such as "USD", "AUD", "UKP" etc.
-
- at item date
-
-For specifying dates. Depending on exactly what is required, you can
-choose to let the user specify an @dfn{absolute} date, a @dfn{relative}
-date such as "one month ago", or "start of the current accounting
-period", or let the user choose how whether to specify the required date
-in relative or absolute terms.
-
- at item account-list
-
-For selecting a particular account or accounts. The UI displays a tree
-of the account hierarchy.
-
- at item multichoice
-
-For selecting one of a group of choices.
-
- at item list
-
-Similar to the multichoice option, but allows the selection of one
-or more items from the group.
-
- at item number-range
-
-For specifying a numeric quantity. The programmer can bound the range
-and precision of the quantity.
-
- at item pixmap
-
-For selecting a pixmap located on the filesystem.
-
- at item color
-
-For selecting a color value.
-
- at item internal
-
-An option that isn't specified through an options dialog box. For
-instance, this is used to store the window dimensions so that they are
-preserved along with other preferences.
- at end table
-
- at node Option Creation, Option Values, Option Types, User Preferences
- at section Option Creation
- at cindex Option Creation
-
-To add an option to an options database, you first create that option,
-then register it with the database. For example, to create a simple
-checkbox-style boolean option, you would use
- at code{gnc:make-simple-boolean-option} to create the option. Once
-created, you can then register the option. With
- at code{gnc:register-option}.
-
- at deffn Function gnc:register-option database option
-Register @var{option} in options database @var{database}
- at end deffn
-
-The example below shows how to create an options database, then register
-a boolean option with it:
-
- at example
-(define gnc:*hello-world-options* (gnc:new-options))
-(gnc:register-option gnc:*hello-world-options*
- (gnc:make-simple-boolean-option
- "Hello, World!" "Boolean Option"
- "a" "This is a boolean option." #t))
- at end example
-
- at subsection Option Creation Functions
-
- at deffn Function gnc:make-simple-boolean-option section name sort-tag documentation-string default-value
-
-Creates a boolean option, with option section @var{section} and name
- at var{name} specified as strings. Note that the section and name strings
-uniquely specify the option for the option database that they get
-registered to, and are used for looking up the option when the value is
-required. @var{sort-tag} is a string tag that specifies the relative
-order when displaying the options. Options are displayed top to bottom
-in case-sensitive alphabetical order. @var{documentation-string} is a
-string containing a short string describing the purpose of the option,
-which the UI displays as a tooltip. @var{default-value} should be a
-boolean value indicating the default value of this option.
-
-Note that @var{section}, @var{name}, @var{sort-tag}, and
- at var{documentation-string} are common to all the following functions.
- at end deffn
-
- at deffn Function gnc:make-complex-boolean-option section name sort-tag documentation-string default-value setter-function-called-cb option-widget-changed-cb
-
-As above, but the function specified in @var{option-widget-changed-cb}
-is called when the GUI widget representing the option is changed (the
-user clicks on the toggle button), and @var{setter-function-called-cb}
-is called when the option's setter is called (when the user selects "OK"
-or "Apply").
-
-One use for having a non-false @var{option-widget-changed-cb} is to make
-another option mutable (in concert with @code{gnc:option-set-sensitive},
-discussed later).
- at end deffn
-
- at deffn Function gnc:make-string-option section name sort-tag documentation-string default-value
-
-Make an option where the user can specify a string.
-
- at end deffn
-
- at deffn Function gnc:make-date-option section name sort-tag documentation-string default-getter show-time subtype relative-date-list
-
-Create a date option. There are three different variations of date
-options, specified by the variable @var{subtype}, which should be one of
- at code{'relative}, @code{'absolute}, or @code{both}. @code{absolute}
-date options allow the selection of a specific day/month/year
-combination. @code{relative} date options allow the selection from a
-list of different dates specified in relation to the current date, such
-as "today", "start of the current month", or "six months ago". Finally
- at code{both} allows the user to choose either using absolute or relative
-date options.
- at end deffn
- at var{default-getter} should be a @dfn{thunk} (Scheme function taking
-no arguments) that returns a pair. The car of the pair should contain
-either @code{'relative} or @code{'absolute}, to indicate whether the
-default value is relative or absolute. If the car is @code{relative},
-then the cdr should be a one of the relative date symbols listed in
- at var{relative-date-list}. If the car is @code{absolute}, it should be a
-timepair containing the default date/time.
-
- at var{show-time} is a boolean that indicates whether when selecting an
-absolute date, the user can specify a time. It is ignored if the
- at var{subtype} is @code{relative}.
-
- at var{relative-date-list} is a list of symbols that indicate the relative
-dates permitted. The symbols used must have been previously defined as
-indicating a particular relative date. @var{gnc:relative-dates}
-contains a list of symbols that have already been set up for the most
-common relative dates. FIXME: document relative date system.
-
- at deffn Function gnc:make-multichoice-option section name sort-tag documentation-string default-value value-list
-
-Create a multichoice option. @var{value-list} is a list of vectors of
-length 3, each representing a different choice. Each vector should
-contain - in the following order:
- at itemize
- at item
-A symbol identifying this choice.
- at item
-A string naming this choice - this string will be the main one
-displayed.
- at item
-A string describing this choice slightly more fully. This string will
-appear as a tooltip.
- at end itemize
-
- at end deffn
-
- at deffn Function gnc:make-list-option section name sort-key documentation-string default-values value-list
-
-Like a multichoice option, but users can select one or more values from
-a list. @var{default-values} is a list of selected values instead of
-just one.
-
- at end deffn
-
- at deffn Function gnc:make-font-option section name sort-tag documentation-string default-value
-
-Allow the user to specify the font. Font options store font descriptions as strings,
-like the X Logical Font Description. You must provide a default value, as there is unfortunately
-no easy way for the GUI to pick a default value.
-
- at end deffn
-
- at deffn Function gnc:make-color-option section name sort-key documentation-string default-value
-scale use-alpha?
-
-Allow the user to select a color. The default value should be a list of
-length 4 containing the red, green, blue, and alpha channel values for
-the color. The scale is the maximum value for a channel, and the
-use-alpha? is a boolean that, if false, disregards the alpha channel
-(note: if you don't know what an alpha channel is, you don't need it).
-
- at end deffn
-
- at deffn Function gnc:make-currency-option section name sort-tag documentation-string default-value
-
-Let the user specify a currency using a currency code. The GUI provides a specialised widget
-for currency selection.
-
- at end deffn
-
- at deffn Function gnc:make-account-list-option section name sort-tag documentation-string default-getter value-validator multiple-selection
- at end deffn
-
- at deffn Function gnc:make-internal-option section name sort-key documentation-string default-value
-Create an option that isn't controlled through the options GUI. This is
-used mainly by the GUI to store state that should be preserved from
-session to session but isn't really configurable from a dialog box,
-such as the size of the GnuCash main window.
- at end deffn
-
- at deffn Function gnc:make-number-range-option section name sort-tag documentation-string default-value lower-bound upper-bound num-decimals step-size
-
-Create an option for selecting a numerical quantity. lower-bound and upper-bound specify the domain of acceptable figures, and num-decimals specifies the range
-to which the option will be displayed (FIXME:and rounded to?). Step-size specifies the step size for the UI's up/down buttons.
-
- at end deffn
-
- at node Option Values, , Option Creation, User Preferences
- at section Option Values
- at cindex Option Values
-
-To get the value of an option, you must first lookup the option in
-the options database.
-
- at deffn Function gnc:lookup-option options section name
-
-Looks up the option in section @var{section} and name @var{name} in the
-options database @var{options}.
-
- at end deffn
-
-
-Once you have looked up the option, you can get its value using
-the function @code{gnc:option-value}.
-
- at deffn Function gnc:option-value option
-
-Get the value of an option. Option values returned are of the same
-type as how the default values are specified (except the date option
-which needs to be fixed).
-
- at end deffn
diff --git a/libgnucash/doc/doxygen_main_page.c b/libgnucash/doc/doxygen_main_page.c
index 5454ff5eea..ca0462a70f 100644
--- a/libgnucash/doc/doxygen_main_page.c
+++ b/libgnucash/doc/doxygen_main_page.c
@@ -7,7 +7,6 @@ This is the new developer and design manual for GnuCash.
The documentation is organised in a rough sequence:
-# \ref manualguide Start with the main GnuCash manual.
--# \ref texihtml Design overview.
-# \ref doxylist Individual topic overviews, linked into the
full API reference for each topic, generated from source code.
-# \ref maingeneral How to work with Doxygen in your own code.
@@ -19,12 +18,6 @@ Please refer to the main
page</a> on the gnucash website which includes links to the
GnuCash Manual and the Concepts Guide in various formats.
-\subsection texihtml Documentation elsewhere in the source tree.
-
-There is also the "GnuCash Design Overview" which can be generated
-from the source using texi2html from the texinfo files in
-src/doc/design, but this is even more outdated.
-
\section doxylist Doxygen overviews.
Where possible, each overview is dated - take care to review older texts
diff --git a/libgnucash/engine/README b/libgnucash/engine/README
index b3aaf6b636..d2f94ec95b 100644
--- a/libgnucash/engine/README
+++ b/libgnucash/engine/README
@@ -7,8 +7,12 @@ There should be no GUI code in this subdirectory, and,
ideally, it should build cleanly and independently of
any GUI elements or assumptions.
-For design documentation, please see the file "design.txt",
-and also, look at the header files carefully. The documentation
-for each routine is in the header files for that routine.
+For design documentation, please read our doxygen documentation.
+This can be found at https://code.gnucash.org/docs/STABLE/
+Alternatively you can build it yourself by running
+ [ninja|make] doc
+The result will be found in
+{builddir}/libgnucash/doc/html/index.html
-September 1998
+The same information can mostly be found directly in the header
+files in this directory as well (though in marked up source format).
diff --git a/libgnucash/engine/kvp_doc.txt b/libgnucash/engine/kvp_doc.txt
index 9b6416ec64..1b51994766 100644
--- a/libgnucash/engine/kvp_doc.txt
+++ b/libgnucash/engine/kvp_doc.txt
@@ -6,8 +6,45 @@ API: \ref KVP
This file documents the use of keys in the key-value pair system
used by the GnuCash Application (both the engine, and non-engine, GUI
-pieces). Before assigning keys for use, please read the Key-Value
-Policy in the GnuCash Design Document located under src/doc/design.
+pieces).
+
+\section kvppolicy KVP Policy
+
+This section defines the policy that programmers should follow
+when using key-value pairs to store information. Because of the
+large amount of information which can potentially be stored using
+this mechanism, it is important to follow these guidelines so
+that order will be maintained.
+
+The following rules should be followed for using key-value pairs:
+
+- This should be used to document the use of keys and values.
+Please consult it before planning any use of new keys.
+
+- Key strings should be in all lower case with the '-' character
+separating words. If possible, use only alphanumeric characters and
+'-'. Example: `bank-info`. Because the '/' character is useful for
+describing keys in sub-frames (`bank-info/routing-number`), do not
+use the '/' character in key names.
+
+- Favor longer, descriptive key strings over short ones. Example:
+`online-banking-info` is better than `onln-bnk`.
+
+- Make use of the fact that frames can be stored in frames. If a group
+of keys are used for a related purpose, consider storing them together
+in a sub-frame.
+
+- Values should generally not be accessed directly through keys, but
+should rather be accessed through specific API calls. The API calls
+do not necessarily need to part a part of the Engine API. For example,
+the GUI would probably define keys that the Engine does not need to
+know about.
+
+- The same key should not be used for different engine structures (Accounts,
+Transactions, Splits), unless the key's value has the same type and the
+same basic purpose.
+
+\section kvpdocformat KVP Documentation format
The format of the data below is:
diff --git a/libgnucash/gnc-module/CMakeLists.txt b/libgnucash/gnc-module/CMakeLists.txt
index 80c997cea5..b8e2e08eea 100644
--- a/libgnucash/gnc-module/CMakeLists.txt
+++ b/libgnucash/gnc-module/CMakeLists.txt
@@ -38,6 +38,5 @@ install(TARGETS gnc-module
install(FILES ${gnc_module_HEADERS} DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/gnucash)
-set_local_dist(gnc_module_DIST_local CMakeLists.txt ${gnc_module_SOURCES} ${gnc_module_HEADERS}
- README)
+set_local_dist(gnc_module_DIST_local CMakeLists.txt ${gnc_module_SOURCES} ${gnc_module_HEADERS})
set(gnc_module_DIST ${gnc_module_DIST_local} ${test_gnc_module_DIST} ${example_DIST} PARENT_SCOPE)
diff --git a/libgnucash/gnc-module/README b/libgnucash/gnc-module/README
deleted file mode 100644
index 5d418aae46..0000000000
--- a/libgnucash/gnc-module/README
+++ /dev/null
@@ -1,6 +0,0 @@
-This is gnc-module, a plugin/module system for gnucash and related
-software. The documentation currently consists of 'doc/design.txt'.
-
-Bill Gribble
-
-
commit 48b9fa80ceac386e40e36e2a7cfc4dc9682fb492
Author: Geert Janssens <geert at kobaltwit.be>
Date: Mon May 20 13:45:44 2024 +0200
Doxygen - strip obsolete info from loans.txt
diff --git a/libgnucash/doc/loans.txt b/libgnucash/doc/loans.txt
index a002488ea2..42a855f1c8 100644
--- a/libgnucash/doc/loans.txt
+++ b/libgnucash/doc/loans.txt
@@ -5,18 +5,6 @@ July, 2002 - jsled at asynchronous.org
API: \ref SchedXaction
-Bugs 84892 and 84877 detail a request for a new Loan/Mortgage account type,
-and Scheduled Transaction support for loan repayment. While it's debatable
-that a new account type is required, there is definitely a need for Scheduled
-Transaction support for interest/payment computation for a parameterized
-"loan repayment SX".
-
-The nature of this support will not create a new top-level account type, but
-instead will result in the following changes:
- a. Support in the SX credit/debit formulas for such calculations.
- b. A Druid to assist in the creation of such SXes.
- [c. budgeting/tool bench support in the future]
-
We define loan repayment values in the following terms:
Identifiers:\n
@@ -253,33 +241,6 @@ structures:
- Escrow -> Expense:Insurance
-/section loansquestions Questions
-
-- UI - visible should all this machination be to the user? Should they even
- see them as such. The current SX since-last-run UI makes them pretty
- visible, and in my estimation it actually helps to make them a bit more
- formal and visible. At the same time, it may be overwhelming for the user
- to have to create formal variables with weird types like "implicit",
- "transient", "static", and "periodic".
-
-\section loansplan Priorities, Plan
-
-The above represents an "ideal" set of extensions to the SX framework to
-enable multiple "enhancement"-level functionalities. Therefore, the
-following is the prioritized schedule, with annotations:
-
--# Functions [PMT, [IP]PMT] in exp_parser; implicit variables [n].
--# [Visual-only] SX grouping
--# Loan-repayment creation Druid
--# SX-only static vars
--# SX-only periodic vars
--# SX-group vars, var_frames
-
-After the completion of item 4, the feature can safely be called "finished".
-Items 5 and 6 only serve to increase the robustness of the facility and make
-the user's life slightly easier, at the cost of making _my_ life harder. :)
-
-
\section loansreference Reference
@@ -323,183 +284,5 @@ Gnumeric supports the following functions WRT payment calculation:
@pmt : payment made each period
@fv : future value
-/section loanspayment Day Two:
-
-As per warlord's comments, the definition of IPMT needs to be updated to
-account for principal pre-payment. IPMT is actually defined by computation
-of the value of an account at a specified point in time. This is significant
-if the loan repayments involve interest.
-
-In the face of creating multiple scheduled transactions for a time range, it
-may be the case that the relevant account balance is not actually posted to
-the account at the time of the variable binding. If we intend to show the
-user an estimation of the IPMT cell value during variable binding, then we
-would need to do something creative about this ... but as it stands, we'll
-leave this as an Exercise for the Reader. :)
-
-\section loansdruid Druid thoughts...
-
-Page Order:
-
-Intro ->
-
-Params ->
-
-Opts ->
-
-Repayment ->
-
-[Insurance ->]
-
-[PMI ->]
-
-[Taxes ->]
-
-Review/Approval
-
-\subsection loansdruidintro Intro
-
-"This is a step-by-step method of creating a loan
- repayment setup within GnuCash. In this Druid,
- you can input the parameters of your loan and
- it's repayment and give the details of it's
- payback. Using that information, the appropriate
- Scheduled Transactions will be created.
-
-"If you make a mistake or want to make changes
- later, you can edit the created Scheduled
- Transactions directly."
-
-\subsection loansdruidparams Params
-
-\verbatim
-Principal : [amount entry]
-Actual Principal : [[optional] amount entry]
-Interest Rate : [numeric entry] %
- Type : [ ] Fixed
- [ ] Variable ---------+
- | Type : 10/1,7/1,...|
- | When : [freqspec?] |
- +---------------------+
-Start Date : [Gnome Date Entry]
-Length : [num entry] [years|v]
- Remaining : [num entry]
-\endverbatim
-
-\section loansoptions Options
-\verbatim
-Do you...
- [ ] ... utilize an escrow account?
- Account: [ acct select |v]
- [ ] ... pay PMI?
- [ ] Via the Escrow account?
- [ ] ... pay insurance?
- [ ] Via the Escrow account?
- [ ] ... pay taxes?
- [ ] Via the Escrow account?
- [ ] ... have some other expense not listed above?
- [ ] Via the Escrow account?
-\endverbatim
-
-\section loansrepayment Repayment
-\verbatim
-Amount : [ amount entry ]
-Assets from : [ account sel |v]
-Princiapl to : [ account sel |v]
-Interest to : [ account sel |v]
-Escrow to : [ account sel |v]
-Remainder to : [{escrow,principal,interest}|v]
-Frequency : +- freqspec ----------------+
- | .... |
- +---------------------------+
-\endverbatim
-
-\section loansinsurance Insurance
-\verbataim
-Amount : [ amount entry ]
-Account : [ account sel |v]
-Frequency :
- [ ] Part of Repayment Transaction
- [ ] Other: +- freqspec ----------------+
- | .... |
- +---------------------------+
-\endverbatim
-
-\section loanstaxes Taxes/PMI/Other
-
-[ same as Insurance ]
-
-
-
-Options in repayment:
-- loan freq != repayment freq
- - floated
- - not
-
-- Where does over-payment go?
- - where
- - into the escrow account
- - directly applied
- - how
- - towards principal [interest is then re-calculated]
- - towards interest [principal is then re-calculated]
-
-- still to do...
- - expression parser/gnc-exp-parser extensions to handle...
- - ...symbols [account names] into functions
- - ...errors better
- - ...iter/count/implicit vars
- - druid...
- - add ipmt', ppmt' calculations, using above
- - kvp storage of "real" data
- - sx grouping
-
-http://www.interest.com/hugh/calc/mort_links.html
-
-\section loansfeedback Druid Feedback:
-
-\verbatim
-<Wilddev> jsled: <auspex> Wilddev: The labels need colons, mnemonics, and right-alignment.
-<Wilddev> <auspex> Wilddev: It may be worthwhile for gnucash to create GtkSpinButton subclasses which show the percent symbol and others within the field.
-<Wilddev> <auspex> Wilddev: I don't know how complicated that will be.
-<Wilddev> <Wilddev> me either :P
-<Wilddev> <auspex> Wilddev: The strings need review, but there may be other changes to make first.
-<Wilddev> <auspex> Wilddev: "Interest Rate Change Frequency" should perhaps be on the next page?
-<Wilddev> jsled: I dont know if you did another page for this, but shouldn't there be a field for ballon amount too?
-<jsled> Excellent feedback; thanks. I don't presently handle balloon payments; how do they work?
-<Wilddev> I think, from what I've read before, the are an amount you pay at the end of the loan to close it
-<jsled> gnc-account-sel == combo box account selection with pull-down account list [like the register] and auto-completion [hopefully]
-
-<Wilddev> <auspex> Is "Length" the length of a period, or the sum of the periods?
-<jsled> The sum of all periods; the length of the loan.
-<Wilddev> he's suggesting to think of a better label for that
-<Wilddev> ah I thought it was the period between loan transactions
-<jsled> Hmm. Okay. The between-transaction period is a frequency editor on the Repayment page.
-<Wilddev> <auspex> I'm wondering if "Original Principal" should be a vulgate
-such as "Loan Amount"
-\endverbatim
-
-
-\section loansexpression Expression changes, round 2
-
-We need the following abilities in order to get mortgage/loan repayment
-working:
-- Ability to get the original value of an account
- - [perhaps, ability to reference an external value?]
-- Ability to get the present value of an account
-- Ability to get the current i in an "i-of-N" sequence
-
-As well, it'd be nice to have:
-- some sort of signature checking on functions in expressions
-- safe[r] error handling?
-
-We decide that the original/present value of the account should be handled in
-scheme, and thus we actually need a way to reference accounts down to the
-scheme expressions. We decide to use the Quote symbols to refer to a string
-literal. The expression parser should be modified to parse this.
-
-The current 'i' and 'N' are going to be handled by having a list of
-predefined variables which the user cannot have access to. For the time
-being, this is 'i' and 'N'.
*/
commit 58b4ee35f0b38113b4a62ffe029de6a1d822743e
Author: Geert Janssens <geert at kobaltwit.be>
Date: Sun May 19 19:46:06 2024 +0200
Doxygen - drop several txt files that were included in
docygen_mainpage.c
None of them had useful information describing actual
implementation concepts or details.
diff --git a/libgnucash/doc/CMakeLists.txt b/libgnucash/doc/CMakeLists.txt
index dc33c60103..ffac542008 100644
--- a/libgnucash/doc/CMakeLists.txt
+++ b/libgnucash/doc/CMakeLists.txt
@@ -4,34 +4,16 @@ endif()
add_subdirectory(xml)
set(doc_FILES
- backup.txt
- books.txt
- budget.txt
callgrind.txt
constderv.html
-# constraints.txt
- currencies.txt
doxygen.cfg.in
doxygen_main_page.c
-# engine.txt
finderv.html
finutil.html
-# g2-architecture.txt
- generic-druid-framework.txt
-# gnc-numeric-example.txt
- guid.txt
loans.txt
lots.txt
- multicurrency-discussion.txt
-# prices.txt
python-bindings-doxygen.py
- qif.txt
README
-# sx.rst
- tax.txt
- TODO-schedxactions
- TODO-sixtp
- user-prefs-howto.txt
)
set_local_dist(doc_DIST_local CMakeLists.txt ${doc_FILES})
diff --git a/libgnucash/doc/TODO-schedxactions b/libgnucash/doc/TODO-schedxactions
deleted file mode 100644
index faa1acf6a7..0000000000
--- a/libgnucash/doc/TODO-schedxactions
+++ /dev/null
@@ -1,584 +0,0 @@
-Author: jsled at asynchronous.org
-
-Main Scheduled Transaction todo list
-------------------------------------
-
-. Bug#102311...
-
- . As per comment 2004-01-05T16:31, there is an issue when other pieces of
- the system change accounts that SXes depend on. We have two options:
- 1: handle change at account-deletion time ["remove this account will
- affect this scheduled transaction ... what to do?"]
- 2: break out of SX since-last-run processing ["this account was removed;
- {edit,delete} SX?"].
-
-##################################################
-### To-Do
-###
-### '.' = to-do, 'X' = done, '?' = jsled verify
-###
-##################################################
-
-. Meta
- . fulfill everything on http://linas.org/linux/gnucash/projects.html#alerts
-
-. FreqSpec.c
- . xaccFreqSpecGetFreqStr [display] needs to go away [?]
-
-X create a template register
- X store account and amount data in kvp_frames.
- . find a way to list multiple registers for template transaction purposes.
- . this is a "normal" general journal + a "stock" general journal
- . warlord's business stuff may extend this to more ledgers...
- . this is going to be: a tabbed notebook in which the tabs contain
- the number of transactions the GL they hold contain.
-
-. register macro-widget [src/register/ledger-core/gnc-regWidget.{h,c}]
- . should support
- . toolbar
- . Close
-
- . Enter
- . Cancel
- . Delete
- . Duplicate
- . Schedule
- . Split
- . Blank
- . Jump
-
- . Transfer
- . Find
- . Report
- . Print
- . popup menu
- . elts
- . Enter
- . Cancel
- . Delete
- . Duplicate
- . Schedule
- . Split
- . Blank
- . Jump
- . extended to support previously-menu-accessible options in embedded case
-
- . status bar
- . configurable UI elts [menu, toolbar, status]
- . re-configurable UI elts
- . menu: the register itself should provide a sub-menu for inclusion
- into other menus [the window-register, for instance]
- . toolbar: As seen above, certain toolbar elts are common, some are
- appl.-specific.
- . status: the status bar is sort-of a boolean option; applications
- may wish to place the status bar in a more acceptable location.
- . default callbacks
- . override-able
- . can "orverridable" mean "[gtk-style-]signal-based"?
- . bitmask of supported functionality
- . !"Schedule..." for the embedded-in-SX-editor case => gray-out
- . shouldn't [necessarily] support
- . date range [may be fixed/irrelevant by caller]
- . style changes [caller may enforce]
- . NOTES/ISSUES
- . pass in prefix for gnc_reg_save_size(...)
-
-? Hook into 'book data changed' save-on-exit decision
-
-. GNCFrequency
- . bugs
- . Bi-weekly / Once
- . Add dupe of start-date control[s]
- . Precedent: monthly, yearly, &c.
- . Bi-weekly, quarterly <= x < yearly
- . Add example[s] -- perhaps wait for dense-calendar widget.
- . yearly-only?
- . if month > current month, choose previous year in start date?
- . Add 'today' button for startDate?
- X transitioning to a new tab doesn't correctly setup the agreement
- between the startdate and the page elements.
- X why does the accounts window go crazy when we change the FreqSpec parameters?
- X probably component-manager related... yup; FreqSpec Malloc/Free
- generates events, which cause GUI refreshes.
- X Example calendar month change isn't handled correctly/doesn't refresh the
- marks.
- X fixed by removing any ability to change the example calendar.
- X "Inappropriate FreqSpec type" on new-SX editing.
- X "new; weekly: click on day, click off day: GLib-CRITICAL **: file gdate.c: line 1236 (g_date_to_struct_tm): assertion `g_date_valid (d)' failed."
- . no longer reproducible
-
-. SX list
- . add a big calendar [gnome-pim? evo?] to SXaction List/overview
- . tab order
- X "** CRITICAL **: file dialog-scheduledxaction.c: line 570
- (row_select_handler): assertion `event' failed." when key-navigating sx
- list.
-
-. SX editor
- . tab order
- . Can't click-out of the register
- B 'ESC' while editing template register causes window to go away badly
- B Can't reliably edit the split values of an added split to a from-trans
- created transaction -- the values get nulled after split-change.
- B Note that this doesn't hold true for just-created splits on a fresh
- SX...
- X attempting to create a Weekly SX with no days selected causes a segfault.
- X the user should be prevented from doing this.
- X composite SX shouldn't segfault when asked to getFreqSpecStr for this
- X should use regWidget
- X Size/space issues [?]
- X auto-shrink on window create [the register is too wide, leading to too
- much whitespace on the two top panels -- sometimes].
- X Un-selecting "End Date" leaves calendar widget sensitive
- X 'Cancel' button should auto-cancel ledger changes
-
-. make-from-transaction
- . bugs
- . general: there's going to be all sorts of interaction issues like these
- between these things [SX-from-trans, SX list, SX editor] that should be
- handled.
- B creating a SX from trans with the SX list open does not update the SX
- list
- X you can delete a freshly-from-trans'd SX from the list with the
- from-trans dlg still open, then 'ok' the dlg to get a segfault.
- X you can generally manipulate SXes into bad/weird states since both
- dialogs are open.
- X So since Advanced editing entails "Simple" editing, it should just
- replace that window. Then, with some CM hookup between the List and
- the Editor, all is well.
- X 20020419 - Wilddev manages to create two SXes from one; the first is
- okay, but the second is h0rk3d [deleting it causes segfault, though it
- can be instantiated correctly].
- X number-of-instances in 'simple' results in "Warning:
- sxftd_advanced_clicked: something bad happened in sxftd_compute_sx"
- . tab-order
- . better frequency guess?
- [ related... ]
- . match existing transactions for long-time users
- . based off template-transaction data, some big existing-transaction
- scanning code.
- X credit/debit pull-over issues
- X need to remove '-' from printed credit value.
- X pull accounts over.
- X pull initial SX name from the Transaction name?
- X need start-date on Make dialog
- X [initially starts as the next occurrence after the created-from SX,
- which may not be the Right Thing]
-
-. need "since-last-run" UI for instanatiation.
- . need nifty visual style for druid.
- . use color-setting code in src/gnome-utils/druid-utils.[ch]
- . support sorting in various clists
- . tab-order
- . variable-binding table:
- . tab through variables -- if on last one: ( if something's unfilled,
- tab back to there, else, tab back to clist:( if no more unfilled
- entries, then tab down to back/next/cancel. ))
- . Double-clicking on auto-create list should jump to transaction
- . register of first split?
- . Need some way to defer to-create SXes?
- . need some configuration for constantly-running GnuCash users of when to
- pop up the 'new scheduled transactions' dialog [option, time-of-day]
- . fix first/last page issues.
- . bugs
- . tab-order on variable-entry window isn't always correct.
- B initial "To-Create Transactions" varbinding table doesn't setup table correctly.
- B correct "Back" button behavior in Druid paradigm
- B created SXes are put in GL forever. :(
- B But this is true of manually-created transactions, too ... is this
- actually correct behavior?
- B creating a bunch [FIXME:define "bunch"] of transactions takes too long
- X with no progress indication.
- B cancelling a bunch [FIXME:define "bunch"] of xactions takes too long
- B no progress indication.
- X twunder reports [2002.01.29] register growing a little bit at a time if
- tab is hit to switch between register fields -- started with update on
- 1/21.
- X I _bet_ this is fixed with magic gnc-regWidget sizing fix -- 2002.04.15
- X "0" and "0.0" don't work for variable values?
- X correct "Cancel" behavior in Druid
- X reset SX state to before creation
- X delete any created SXes.
- X restore any obsolete-n-deleted SXes.
- X variable expressions don't get re-eval'd [as formula]?
- X need to do this only on tab-out of the field.
- X need effective cancellation support
- X Change from dialogs to druid
- X/O create transactions
- X numeric
- X formula
- X need variable fill-in UI...
- X re-use gnome-sheet code for a variable-binding table? -- ended up
- using GtkTable [for now?]
- X variables should default to '0', and '0' should be acceptable.
- X need way to expire/purge scheduled transactions which have no chance of
- being created [outside their end date; once-scheduled and past].
- X infrequent enough that a dialog should suffice.
- X need 'reminders' of upcoming scheduled transactions during since-last-run
- X Is it sufficient to look at the next instance of ea. transaction only?
- I think not... we probably want to look out until the transaction is
- outside the reminder range.
- X Should deal with "nothing-to-do" better [not even show up in the worst
- [read: no auto-notify/to-create/reminders] case].
- X don't load/init/create the GUI if we're not about to use it.
- X this is different between the auto-invoked since-last-run dialog [show
- nothing] and the menu-invoked since-last-run [show a dialog to the user
- stating there's nothing to do].
- X double-clicking a reminder should [probably] move it up to the to-create
- list.
- X Easy UI way of moving through the SXes which need variable bindings.
- [This presently is: click "Ok" and the next clist row which needs
- bindings is selected.]
- X any [horizontal] window size change height-grows the top/auto-create GL.
- X always goes one date past the instantiation date.
- X credit and debit seem reversed at instantiation time...
- X this is fixed, but is the fix correct?
-
-. register mods?
- . to see upcoming xactions, modifying future balance?
- . to note which are "recurring"
- . the mozilla "reload" glyph is kinda neat...
- . prolly should use existing PIM "recurring" glyphs
- . Differently-colored "not-yet-created" entries for a configurable
- time window?
- . Context menus/sensitive toolbar button/menu item for creation of
- not-yet-created transactions?
- . The ability to turn a non-recurring transaction into a recurring one...
- X [see from-trans section]
- . inactive cells
- X date
- . recn?
-
-. deal better with formulas in template transactions [real FormulaCell]
- . actually do something with the result of the balancing computation
- / recognize purely numeric template transactions and balance at
- template-creation time.
- / balance transaction with vars?
-
-. GNCFrequency
- . initial-settings synchronization [start date, optionmenus]
- . only a couple left; which ones?
-
-. backend support
- . SQL
- . others?
-
-##################################################
-### Done
-### ... don't put stuff here ... just move it to the bottom of the
-### appropriate list, above, and 'X' it -- jsled
-##################################################
-
-X add the ...GetFreqStr() code for the complex composite FreqSpecs
-X fix the ...GetNextInstance() code
-X XMLv2 I/O
-X need policy for start-dates in GNCFrequency
-X fix GetNextInstance and GetInstanceAfter, mostly for composite FreqSpecs
- X also needs to deal with >28-mday values WRT last-occur date + multipliers
-X Engine ...Init() functions should be private.
-X would like "don't even tell me you instantiated it, just fscking do
- it!" option for non-manual-conf SXes
-
----------------
-Random Notes
-
-. SX Creation...
- . Creation occurs due to a variety of circumstances:
- . A user opens a register with future transactions in it; they manually
- force the creation of the [perhaps not immediately next [though this
- seems a bit weird]] one.
- . A user is reminded of something which hasn't come due, but will w/in a
- configurable amount of time, and thus they pay/create it.
- X GnuCash starts and hasn't been run in some length of time; the
- transactions which have "come due" since the last run are available for
- creation.
-
-. Configuration options...
- . Overall
- X Size of template register window
- . color of future register entries
- . conrad's desires
- X policy
- X create for N days in advance
- X show for N days in advance, create when come-due
- X defaults
- X create/show for 'N' days in advance
- X remind me 'M' days in advance
- X just create
- X notify when created
- X Per-SX
- X just create/notify
- X create/show
- X lead-time
- X reminder
- X lead-time
-
-
-
-. [NOTES] Dealing with SX state-changes
- . Create-into-future vs. create-normal
- . into-future -> normal : no change; the last_occur date will be
- appropriate, and will catch up eventually [unless the have-been-created
- transactions should go away]
- . normal -> into-future : should create immed, or wait for user?
- . into-future [t_0] -> into_future [t_1]
- . frequency
- . in presence of create-into-future?
- . transaction
- . in presence of create-into-future?
-
-
-##################################################
-### Bugs
-##################################################
-
-X General
- X Date l10n.
-
-. GNCFreqency
-
-. Since-last-run
-
-. SX-from-trans
-
-##################################################
-### Enhancements
-##################################################
-
-. SX name should be default value for template transaction description
-. loan/repayment SX's
- . integrate "Financial Calculator"
- . auto-determine number of occurrences/end condition from liability
- account amount.
-. SX since-last-run should be able to sort by Date [conditional on the dialog
- staying around].
-. There probably wants to be a multi-month "example" View which the
- GNCFrequency can work with.
- . jalapeno/ben has some thoughts on this...
-. Evolution calendar integ.
-. Evolution To-Do list integ. [SX reminders]
-
-========================================
-
-Template Registers/Transactions
-
-Template-option registers are used for users to enter the template
-transaction to be created when the scheduled transaction comes due.
-Most fields will be copied directly, but certain fields will need to
-be modified upon instantiation, and the template version of these
-transactions will need to contain the information necessary to do that
-instiantion. For some fields, this will be a derivable quantity, and
-for others the user will need to be prompted. This will show up
-mostly for the amount of variable-amount transactions; perhaps the
-amount is then derivable from some external source. These amounts
-will then be represented by a variable, a function, or a formula
-including both.
-
-Examples...
-
-Verizon bill: "108.83 +- x"
- . x: tax amounts [user-input]
-Power: "seasonal_util_gas( 'OAK_CA', '100 therms' ) + seasonal_util_elec( 'OAK_CA', '220 kwhrs' )"
- . seasonal_util_gas( loc, amt ): regional/seasonal power price
- . seasonal_util_elec( loc, amt ): regional/seasonal electricity price
-Rent: 1900
-Phone: "26"
-Internet: "80 - 40 - 10" [3 splits]
-Daily: "4 + 6 (+ 26)"
- . 4: cigarettes
- . 6: avg lunch
- . (opt) 20: wine
-Gas: "regional_auto_gas( 'BERK_CA', 'premium', 14 gal +- 2 )"
- . regional_gas( loc, type, formula )
- . loc: location
- . type: subclass of gasoline
- . formula: formula to use for user-query
-TROA: "220.14"
-
-User-input
-
-When user input is required for scheduled transaction instantiation,
-we should have some sort of simple, spreadsheet-like UI for the entry
-and verification of values. This would allow the entry of all values
-necessary for the formula to be calculated.
-
-We also need a way to defer instantiation of a scheduled transaction
-until the information can be obtained.
-
-Example...
-
- type | date | formula | variable | value | total
-+---------------------------------------------------------------------------+
-| PG&E | 2001.04.12 | lookup(x) + lookup| | | 184 |
-|---------------------------------------------------------------------------|
-| | | | x | 142 | |
-|---------------------------------------------------------------------------|
-| | | | y | 42 | |
-|---------------------------------------------------------------------------|
-| gas | 2001.03.01 | cost/gal * gal | | | |
-|---------------------------------------------------------------------------|
-| | | | cost/gal | 1.949 | 14.27 |
-|---------------------------------------------------------------------------|
-| | | | gal | 12.32 | |
-|---------------------------------------------------------------------------|
-| gas | 2001.03.12 | cost/gal * gal | | | |
-|---------------------------------------------------------------------------|
-| | | | cost/gal | 1.959 | 15.39 |
-|---------------------------------------------------------------------------|
-| | | | gal | 13.43 | |
-+---------------------------------------------------------------------------+
-
-** Of course, "cost/gal" is going to be interpreted as division; perhaps we
-can a) not handle it or b) have a heuristic. :(
-
-I believe this means we can use the existing gnc-sheet/register-style
-thingy.
-
-We probably want to defer the lookup-based stuff until
-1.8/2.0/gnumatic-provided network backing for this.
-
-Stocks/recurring share purchases can make use of this, as well. The
-idea is then, probably, that the user will have a fixed amount with
-which to buy as many shares as possible; the num-shares, then, is a
-formula based on a lookup at the given time [the share price],
-involving the function FLOOR.
-
-It'd be nice if this formula could be either a simple infix syntax for
-normal people, or a sexp for Schemers.
-
-=================================================
-
-Instantiation Notes
--------------------
-
-<jsled> Wilddev, conrad: Something that came out of Aaron's mail [see my reply to -devel] that I'd like your comment on:
-<jsled> How do you intend to use scheduled transactions?
-<jsled> Do you intend to use it to create things have should be in there since you last ran GnuCash?
-<jsled> Or, do you intend to use it to create future transactions [perhaps a weeks worth] before they occur?
-<jsled> Or, just primarily the former, but use the fact that the future transaction will be in the register to remind you to pay things, &c.?
-
-<conrad> Personally, I'd be looking at future transactions as a reminder thing. But then, I run gnucash every day.
-<jsled> conrad: Do you re-invoke it every day, or leave it running?
-<conrad> I can see other people wanting case 1 though.
-<conrad> I leave it running.
-<jsled> conrad: Interesting. You'd want some sort of "new-day" check/timer, then, to re-display the "create new transactions" dialog... or do you want to control it?
-<jsled> the idea is that upon startup, if there are new transactions to create, the dialog will come up [configurable, but that should be the default].
-<conrad> I think a further configurable sub-option should be "redisplay on change of day" (possibly with an "at time <blah> option?)")
-<conrad> without that option, it will not do what I'm counting on it to do - remind my I'm supposed to pay my bills.
-<jsled> Yup yup.
-
-
-Summary...
-
-conrad wants to use this to remind him to pay his bills. He runs GnuCash
-continuously, and thus wants an option to "pop-up on day change [at time
-HH:MM]". He's interested in seeing future transactions as well as what's
-being created ATM.
-
---------------------
-
-window-register notes:
-
-. RegWindow *regWindowSimple (Account *account)
-. RegWindow *regWindowAccGroup (Account *account)
- . functionality should remain, probably in reg mwidget
- . I now disagree; this should be the caller [for templates, especially]
-
-. void gnc_register_raise (RegWindow *regData)
- . probably should remain here; if the reg mwidget has knowledge of it's
- containing window, then it can go there.
-
-. void gnc_register_jump_to_split(RegWindow *regData, Split *split)
-. void gnc_register_jump_to_split_amount(RegWindow *regData, Split *split)
- . should be part of mwidget
-
-. static void gnc_register_change_style (RegWindow *regData, SplitRegisterStyle style)
-. static void gnc_register_style_(ledger|auto_ledger|journal|double_line)_cb (GtkWidget *w, gpointer data)
- . mwidget [no]
-
-. static void gnc_register_sort_(standard|date|date_entered|date_reconciled|num|amount|memo|desc)_cb(GtkWidget *w, gpointer data)
-. static void gnc_register_sort (RegWindow *regData, sort_type_t sort_code)
- . mwidget? -- actually seems like container's responsibility.
- . then, need some way to get the ledger->query for manip.
- . some of these may not make sense in embedded applications
-
-. static time_t gnc_register_(min|max)_day_time(time_t time_val)
- . eh? This should probably be a util function somewhere
-
-. static void gnc_date_range_set_sensitivities(RegWindow *regData)
-. static void gnc_register_set_date_range(RegWindow *regData)
-. static void gnc_register_date_cb(GtkWidget *widget, gpointer data)
-. static void show_all_cb(GtkWidget *widget, gpointer data)
-. static void gnc_register_today_cb(GtkWidget *widget, gpointer data)
-. static void gnc_register_date_toggle_cb(GtkToggleButton *toggle, gpointer data)
-. static void gnc_register_date_changed_cb(GtkWidget *widget, gpointer data)
-. static void gnc_register_show_date_window(RegWindow *regData)
-. static RegDateWindow *gnc_register_date_window (RegWindow *regData, gboolean show_all)
- . need DateWindow policy/decision.
- . decision: caller's responsibility.
-
-. static GtkWidget *gnc_register_create_tool_bar (RegWindow *regData)
- . mwidget
- . should use passed-in toolbar, with clear contract about how the caller
- should add/manip the [modified] toolbar provided.
-
-. static void gnc_ui_find_transactions_cb (GtkWidget *widget, gpointer data)
- . necessary for embedded applications? [nope]
-
-. static GtkWidget *add_summary_label (GtkWidget *summarybar, const char *label_str)
- . mwidget [option]
- . eh?
-
-. static GtkWidget *gnc_register_create_summary_bar (RegWindow *regData)
-. static GtkWidget *gnc_register_create_status_bar (RegWindow *regData)
- . mwidget [options]
-
-. void gnc_register_jump_to_blank (RegWindow *regData)
- . helper for various callbacks
- . mwidget
-
-. static void expand_trans_check_cb (GtkWidget *widget, gpointer data)
-. static void new_trans_cb (GtkWidget *widget, gpointer data)
-. static void jump_cb(GtkWidget *widget, gpointer data)
-
-. static GtkWidget *gnc_register_create_menu_bar(RegWindow *regData, GtkWidget *statusbar)
- . mwidget
- . should take menubar as param
-
-. static GtkWidget *gnc_register_create_popup_menu (RegWindow *regData)
- . mwidget
- . should take popup as param
-
-. static void gnc_register_destroy_cb(GtkWidget *widget, gpointer data)
- . needs to integrate more nicely
-
-. RegWindow *regWindowLedger (GNCLedgerDisplay *ledger)
- . Creates the ledger :)
- . Sets up the data struct :)
- . Creates a gtk_window_new :(
- . Creates a gnc_register_date_window :I
- . Creates the statusbar, toolbar, popup, menubar :/
- . recalls saved window_size from prefix [param]
-
-. static gnc_numeric gnc_account_present_balance (Account *account)
-. static GNCPrice *account_latest_price (Account *account)
- . mwidget? [nope ... in fact, not even in window-register]
-
-. static void startRecnCB(GtkWidget * w, gpointer data)
- . recn: configurable behavior
-
-. static gboolean gnc_register_include_date(RegWindow *regData, time_t date)
- . date-range stuff.
-
-. static gboolean trans_has_reconciled_splits (Transaction *trans)
- . util
-
-. static DeleteType gnc_transaction_delete_query (GtkWindow *parent, Transaction *trans)
- . default is probably good; mwidget
- . ideally have way to customize text
-
-. static void gnc_register_check_close(RegWindow *regData)
- . should be mwidget util fn
-
-. static void report_helper (RegWindow *regData, SCM func, Query *query)
- . mwidget util
diff --git a/libgnucash/doc/TODO-sixtp b/libgnucash/doc/TODO-sixtp
deleted file mode 100644
index cf421f4af3..0000000000
--- a/libgnucash/doc/TODO-sixtp
+++ /dev/null
@@ -1,33 +0,0 @@
-
- bust this file up into several. Its *way* too big to deal with.
-
- create common funcs for repeated "types" of parsers. i.e. a common
- func for handling guid, gnc_numeric, etc. parsers - just pass in
- string->data and data->string funcs.
-
- change sixtp_child_result to sixtp_result?
-
- add generic accumulate chars node constructor - takes end_handler
- as argument - same as for timespec parser...
-
- document that right now parsing is *extremely* anal - no whitespace
- surrounding data.
-
- need to add a way to propagate error data upward...
-
- do we need a way to pass an object up through the tree along with
- its lower level destructor?
-
- CHECK TO SEE IF WE ALWAYS DTRT IN THE END TAG HANDLER - IE DO WE
- CLEANUP PROPERLY SINCE AT THAT POINT THE FRAME CLEANUP HANDLER WILL
- **NOT** BE CALLED.
-
- CHECK TO SEE THAT WE'RE SETTING SHOULD CLEANUP TO FALSE EVERYWHERE
- WE SHOULD (i.e. when we use the result)!
-
- DAMN, why didn't I think of this before. I should have added a
- parent "after-child" hook. I think that might have greatly
- simplified some of the nodes...
-
- Do we also want "before/after" chars handlers?
-
diff --git a/libgnucash/doc/backup.txt b/libgnucash/doc/backup.txt
deleted file mode 100644
index 841db36ab1..0000000000
--- a/libgnucash/doc/backup.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-/** \page backuppolicy Backup Design
-
-API: \ref Backend
-
-Currently, backups and log files are automatically stored by the engine
-with date/time stamps every time the user hits 'save' in the gui.
-
-(The actual file writing is done by xaccWriteAccountGroupFile() in
-in src/engine/FileIOP.h)
-
-\section backupchanges Proposed design changes:
-
--# Allow user to configure which directory backups should be put into.
- (currently, this is same as current directory). Requires changes to
- engine FileIOP.h as well as GUI.\n
- One possible default is ~/.gnucash/data/ (Which is supposed to
- be the place where files are saved if no directory is specified.!?)
--# Prompt the user to make a backup every third save. Make this number
- configurable. If no default backup path set, prompt to set it,
- with suggested path being ~/.gnucash/backups/
--# If save format was XML text, then could use RCS ...
- Alternately,
- For those that don't know, xdelta is like RCS, but it's designed to
- handle any kind of data, including binary, is supposed to work really
- well, and transparently handles gzipped data with some form of MD5sum
- verification. It's also available in library form. Like RCS it would
- give us the ability to do cool things like snapshot the data every so
- often for nearly no cost. Want to see what things looked like 6
- months ago? Just enter the right date into the "time-warp" dialog :>\n
- For those on Debian systems, just install the xdelta and
- libxdelta2-dev packages. Others can get the source from
- ftp://www.xcf.berkeley.edu/pub/xdelta/, or just go to
- ftp.debian.org:/pub/debian/dists/unstable/main/source/utils/xdelta*.tar.gz
--# Could monitor how many changes (records altered) the user has made,
- and could prompt for more frequent saves if lots of editing has
- occurred...
-
-*/
diff --git a/libgnucash/doc/books.txt b/libgnucash/doc/books.txt
deleted file mode 100644
index 9524b86b75..0000000000
--- a/libgnucash/doc/books.txt
+++ /dev/null
@@ -1,427 +0,0 @@
-/** \page bookperiods Books / Accounting Periods
-
-API: \ref Book\n
-
-\section periodsintro Implementation Overview
-
- Linas Vepstas <linas at linas.org> December 2001
- Last Updated August 2003
-
-A top, unimplemented request for GnuCash is the ability to 'close
-the books', that is, to add support for 'accounting periods'.
-Partial support for books has been added to the GnuCash engine;
-and a GUI is partially finished. This file reviews the
-implementation design choices and the current design status.
-
-\subsection periodsdefines Definition
-
-An accounting period or 'book' is a set of accounts and transactions
-that, once closed, must never be modified again. Books are typically
-closed once a quarter, or once a year. Generating a report from a
-closed book tells you how well you did for that year (or quarter).
-The provision against modifying a closed book helps ensure correctness,
-and discourages cheating. Note that the closing balances of a closed
-book must be carried forward as the opening balance in the next book.
-(But only for asset, liability and equity accounts. Opening balances
-are zeroed for income and expense accounts.)
-
-Note that the correct handling of depreciation, capital gains and
-other similar accounting concepts requires 'Lots' to be correctly
-handled. Lots are a way of identifying that an item bought in one
-transaction is the same as that sold in another transaction.
-When a book is closed, the entire lot must be brought forward,
-and not just the account balance, because depreciation, capital
-gains, taxes, etc. depend on the dates of the originating
-transaction. See 'lots.txt' for details.
-
-API: \ref Lot
-
-\subsection periodsrequired Requirements
-
-Must have good performance (large data files usually mean poor performance).
-Use the idea of 'books' to prevent file bloat. Must have access to
-historical data. Must be able to create bar-charts, graphs, reports
-of multi-year data (i.e. create reports spanning multiple books).
-
-\ref Period
-
-\subsection periodsstatus Status
-
-The top-level structure that holds references to all of the data in
-a book is implemented in src/engine/qofbook.c. The routines to
-split one book into two, automatically setting account balances,
-etc. are implemented in src/engine/Period.c. The actual
-implementation used is "Plan A" from the list of choices
-below. The actual implementation is not yet complete, see
-"Implementation Notes" at bottom for the current status.
-
-\section periodssolution Possible Solutions
-
-API: \ref Query
-
-Listed in order from worst to best:
-
-\subsection periodsdelete Plan F:
-
-Simply 'delete' old transactions, and adjust the equity to make up for
-this. More specifically: Split one file into two, with only 'old'
-transactions in one, and only 'new' transactions in the other.
-
-I believe that this can be 'easily' coded by creating a second instance
-of a qofbook structure in memory, copying all the account info
-into it, and using Query.c to copy in only the 'old' transactions.
-(and v.v. using Query.c to delete the old transactions in the other copy.)
-Then, look up the ending balance on all asset/liability accounts
-in the 'old' book, and create new transactions in the 'new' book
-that transfers that balance amount to an equity account.
-The transfer description is, of course, 'opening balance'.
-Balances of income/expense accounts are zeroed out.
-
-I believe this code would be easy to write in C or scheme. There may be
-a few bugs/difficulties lurking in qofbook that might trip things up.
-Also, at a minimum, there needs to be a GUI dialog, asking for the
-date on which to close the books.
-
-(A fancy but optional GUI dialog/wizard might ask 'which equity
-account to transfer the opening balances, and what the description
-should say. This GUI is optional, since, after all, these can be
-tweaked by hand, and its only done once a year or once a quarter.)
-
-(An even fancier GUI would remember how often the books should close:
-1,2,3,4 times a year, 12 times a year, whatever, and 'remind' you
-when that happens.)
-
-(Another 'fancy' feature might be to not allow user to close book until
-all 'old' transactions have been cleared/reconciled. But that might be
-a bit much for non-bank accounts).
-
-API: \ref Transaction
-
-\subsection periodsf Pros & Cons of plan F:
-
-- pro: simple. The simplest option.
-- pro: truncated file loads much faster
-- pro: old/irrelevant accounts can be safely deleted from newest file
- (while still being preserved in old files).
-
-- con: impossible to generate 5 year reports, multi-year graphs. This
- would really hurt, esp, when tracking stocks/mutual funds/retirement
- accounts over a number of years.
-
-I think this last one is the Achilles heel, the torpedo in the rudder
-that sinks the boat.
-
-\subsection periodspland Plan D
-
-As above, but instead of deleting, add a kvp to each transaction stating
-'/book/closed-on=12.31.2000'. Then modify the default query for the
-registers so that the only displayed transactions are those that are *not*
-part of a closed book. Modify the Query GUI dialog to add 'book' as
-a query parameter.
-
-- pro: easy access to historical record
-
-- con: slow loads; file size not reduced.
-- con: dealing with opening balances, equity, is icky.
-- con: can't delete/hide old/stale accounts.
-
-We move on....
-
-\subsection periodsplanc Plan C
-
-As in plan F, but instead of creating two books, clone the account tree
-into two: 'old' and 'new'. The old and new accounts are identical,
-except that they get different guid's. Every account in the old
-tree gets a kvp in it: '/book/closed-on=12.31.2000'. We don't copy
-or delete any transactions; instead, we reclassify them: Old transactions
-are transfers between old accounts, new transactions are transfers
-between new accounts.
-
-The account summary needs to be modified to show only 'new' accounts
-by default. The transfer-from pop-down needs to be modified to show
-only 'new' accounts only, and never the old accounts.
-
-Transfers between closed and open accounts are never allowed (this is
-validated/forced in the engine). Opening balances are handled just as
-in plan 'F'. User can only view data in closed books, and not change
-it.
-
-If we allow books to be re-opened, then the 'starting balance' equity
-transfers must be deleted. We can save 're-opening' for some future
-day.
-
-The 'starting balance equity transfers' must have a kvp pair in them:
-'/book/closing-balance-of-account-guid=0xdeadbeef'.
-This way, we know that this transaction is associated with the closure
-of the book on some specific account, and that way, we can find this
-transaction someday in the future, if we ever need to.
-
-Each new account needs to point back at the copy that is its 'old' self.
-(these don't have to be C pointers, they could be some suitably clever
-kvp: '/book/previous-guid=0xdeadbeef') This continuity is needed in order
-to be able to create reports that scan over multiple books. The Query.c
-interface needs to be modified so that it searches only new accounts,
-or it searches new accounts *and* their corresponding 'old' copies.
-
-(There are three ways to deal with this account continuity issue:
-- don't deal with it in query.c: force various GUI dialogs to explicitly
- formulate queries involving the /book/previous-guid string.
- but this gets messy in the GUI's. May lead to excess cut-n-paste
- of similar code between different GUI's.
-
-- 'hide' the distinction between 'old' and 'new' in query.c:
- the users of query.c need only to specify a boolean flag: search
- closed books: yes/no. However, this is conceptually ugly, and
- prevents query from doing low-level queries on specific
- books.
-
-- create query utility wrapper/pre-processor that takes a query,
- and then modifies it to search through closed books as well.
- This is the 'cleanest' solution. ??
-
-- All these are delicate, and need a little more thought and
- exploration. Goal is to simplify queries, not burden the system
- with cryptic, complex code.
-)
-
-I believe that if we can deal with the account-continuity issue in query.c
-or in a wrapper thereto, that there are no remaining issues with
-reporting. i.e., for any given report, we are either reporting
-data in closed books, or not. Different reports should have different
-defaults. e.g. income/expense pie chart never looks at old books.
-asset-value-over-time-bar-chart always looks at closed books.
-
-
-- pro: safer than plan F, since we really can enforce the 'you aren't
- allowed to edit closed books' rule.
-- pro: solves the old-account/new-account problem, since new accounts
- can be edited/deleted without damaging old account.
-- pro: solves the historical reporting problem.
-
-- con: queries are potentially slow, loading of file is potentially slow.
-
-But now we have enough info to propose the final solution:
-
-\subsection periodsplana Plan A:
-
-The kvp markup of plan C coupled to the multi-file solution of plan F.
-In initial startup of GnuCash, only the 'current' book is loaded.
-If user asks for a report that requires data from old books, then
-we have to pause to load one or more of the older books.
-
-If the books are stored as separate files, then the 'current' book
-needs to somehow know the filenames of the old books. I recommend
-against storing the books as different sections of one file, for
-many reasons:
-- risk of corruption of old books
-- bloated file size
-- the single-file solution would need to invent a 'directory' so
- that the location of the old books in the file can be quickly
- found and lseek()'ed or mmap()'ed. But why invent a directory?
- Unix already provides directories!
-
-I recommend that every book get a unique guid. The current book
-would know the guid's if its closed book progeny. The filename
-would incorporate some compressed version of the guid (and/or
-the date of closure).
-
-Optional:
-every book gets not only a unique guid, and also stores some
-meta-information (as book-level kvp's):
-
-/book/title=some-user-supplied-name\n
-/book/notes=user-supplied-descriptive-comments\n
-/book/start-date=xxx\n
-/book/end-date=xxx\n
-/book/previous-book-guids=(list 0xa 0xb 0xc)\n
-/book/accounting-period=enum {none, week, month, quarter, trimester, year}
-
-\subsection periodsaprocon Pro's & Con's
-
-I am not aware of any con's to plan A at this point.
-
-\section periodsoverview Implementation Overview
-
-Plan A has been implemented in the engine. To quickly summarize:
-- Partitioning involves splitting one book into two, called the
- "old, closing book", and the "current open book".
-
-- Accounts are copied between old and new books. One of the copies
- is issued new GUID's, but the rest of the account data is copied.
- KVP pairs are then added so that each copy points at the other,
- and can thus be easily found. The "gemini" KVP keyword is used.
- The opening balance is zeroed for income accounts. A transaction
- is created to set the correct opening balance on asset accounts.
- The transaction is a transfer from equity. An equity account is
- created automagically, if needed.
-
-- Transactions. Transactions are partitioned, and end up either
- in the old or the new book. Splits move with transactions.
- Note that some transactions, associated with open lots, may be
- kept in the new book (See below).
-
-- Lots. If a transaction has a split in an open lot, then that
- transaction is not moved to the closed book. It needs to stay
- with the open book. If a lot is closed, and all of the other
- lots associated with all of the transactions in this lot are
- also closed, then the lot may be moved to the closed book
- (and all of the other associated lots must then also be moved).
-
-- Prices. Prices are sorted into the new and old books according
- to the date on the price.
-
-- Scheduled transactions/recurring transactions. These are left
- in the new book, untouched. They are not copied into the old
- book, and no trace of their existence is left in the old book.
-
-- Business Objects. Not implemented.
-
-\section periodsnotes Implementation Notes
-
-- src/engine/Period.[ch]
- Implements the main logic to split one book into two, and populate
- it with the appropriate keys, markup, etc. and to carry balances
- forward, etc.
-
-- src/engine/gnc-lot.[ch]
- Implements accounting Lots.
-
-- src/engine/Scrub2.[ch]
- Implements simple FIFO for lots. Data is scrubbed with respect to
- this FIFO before the books are closed. Commodity accounts (e.g.
- stock accounts) must have a coherent Lots structure before books
- can be closed. The scrubber makes sure there's nothing hanging
- out.
-
-- src/gnome/druid-acct-period.[ch]
- Implements a druid interface to allow user to specify book closing
- dates, add a title and notes to a book, and walk through the process.
- Uses FreqSpec.[ch] and the widget in gnc-frequency.[ch] to allow
- the user to specify the frequency of book closings.
-
-- The XML-file backend can store multiple books in one file. There
- is currently minimal support for writing out multiple books,
- one per file (this enables faster load, by not loading old books).
- There is currently no support for loading multiple books from multiple
- files.
-
-- (Details about the dbi backend are missing.)
-
-\section periodsannounce ANNOUNCE: Book Closing Beta 2
-
-Books AKA Accounting Periods can now be closed by going to the 'Action'
-menu on the main window, and selecting 'close books'. This will popup
-a druid that will allow you to select closing dates. Books are closed
-one at a time: after each one, you can go back and alter the close date.
-A book is 'closed' by moving transactions and prices earlier than the
-indicated date to a separate file.
-
-As a side-effect of book closing, capital gains (losses) will be
-automatically computed using a FIFO accounting method. Stocks
-or other non-cash assets that haven't been sold will remain in the
-currently open book, even if the purchasing transactions were made
-a long time ago.
-
-The biggest drawback to the automatic computation of the gains/losses
-is that there is no GUI to specify alternate accounting methods
-(e.g. LIFO, or hand-picked lots, etc.) There is basically no practical
-way to 'undo' the results of the gain/loss computations.
-
-The other main drawback to book closing is that this will prevent
-multi-year (multi-period) reports & graphs from being generated.
-The old data will be in separate files, and there is currently no
-way to load several files at once.
-
-\section periodsissues Open Issues/Questions that Need Discussion:
-
-- How to handle business objects? e.g. vendors, customers should be
- copied into both old and new books. But invoices should be in one
- or the other. Need to document which is which.
- Copy:
- customer -- ok, has guid, has for-each
- employee\n
- No-op:
- address -- do nothing
-
-- Discussion Q: What should the naming convention be for the different
- books? When the XML file backend is used, different books need to be
- stored as different files (in order to avoid the performance
- penalty of a large file load). Currently, what's implemented is\n
- book-1dc750aa3e6fd045c13ac8afb1a9ac03-my-gnucash-file.xac.gml\n
- where the number is the GUID of the closed book (needed to be able to
- quickly find the book/file) and 'my-gnucash-file.xac' is the name of
- the original file whose books were closed.\n
- Need to change the name to include the word "archive".
-
-- Discussion Q: When saving books, make the book title part of the
- book name (user convenience).
-
-- Should closed books be allowed to have unreconciled transactions?
- Answer: probably. Should there be a warning?
-
-\section periodstodo Open Issues / ToDo
-
-- Change GUI to allow user to specify a default equity account
- for dealing with opening balances. Should be done with kvp markup.
-
-- Fix crash when exiting gnucash after closing books.
-
-- The filename of the old, closed books should probably be saved
- in the KVP tree of the current open book. This need be done only
- from the file backend.
-
-- Need to mark closed book as unalterable, and respect that markup.
- I think there's a 'closed' flag in the book, but I don't think its
- respected.
-
-- The book closing GUI (druid-acct-period.c) needs to save/restore
- period end date (the FreqSpec) to KVP on open book. This would be
- easy once we have a freq-spec-to-kvp and freq-spec-from-kvp routines.
-
-- Handling of lots in book closing is implemented but is poorly tested.
- Need to write test cases. Also test cases for prices in book
- closing.
-
-- price-saving in the SQL backend is probably broken, its certainly
- untested. Need to remove old deprecated price-lookup mechanism,
- and replace w/ qofquery.
-
-- Need to provide for loading of closed books, because this is needed
- for reports.
-
-- Handling of multi-book reports ??? Need to work out the recommended way
- of making this happen....
-
-- Have some way of remembering the quickfill text from older books.
-
-- Possibly neat idea:
- Book closing, as currently implemented in the GUI, is driven entirely
- by the date-posted. There is no (planned) interface to allow you to
- exclude some certain transactions from a particular closing (although
- it would be 'easy' to add this: right before I close a book, I have a
- list of transactions which can be added to/removed from).
-
-- add 13-period support to FreqSpec and the FreqSpec widget.
- e.g. from the mailing list:
- One of the calendars my company uses is like this:
- 13 periods
- 1st period begins jan 1st, partial first week plus 4 weeks.
- 2nd - 13th period begins on a sunday every four weeks.
- 13th period - 4th week may be less than full week because it ends on 12/31.\n
- For 2003:\n
- 01. 01/01 - 02/01\n
- 02. 02/02 - 03/01\n
- 03. 03/02 - 03/29\n
- 04. 03/30 - 04/26\n
- 05. 04/27 - 05/24\n
- 06. 05/25 - 06/21\n
- 07. 06/22 - 07/19\n
- 08. 07/20 - 08/16\n
- 09. 08/17 - 09/13\n
- 10. 09/14 - 10/11\n
- 11. 10/12 - 11/08\n
- 12. 11/09 - 12/06\n
- 13. 12/07 - 12/31\n
-
-*/
-=========================== end of file ========================
diff --git a/libgnucash/doc/budget.txt b/libgnucash/doc/budget.txt
deleted file mode 100644
index abacbfbfe8..0000000000
--- a/libgnucash/doc/budget.txt
+++ /dev/null
@@ -1,225 +0,0 @@
-/** \page budgetplan Some Thoughts about GnuCash Budgeting
-
-API: \ref Budget
-
-Bob Drzyzgula
-
-18-April-1998
-
-\section budgetabstract Abstract
-
-At this point, this document contains my personal thoughts about possible
-design criteria for a budgeting engine in GnuCash. These should not
-at this writing be taken as consensus opinion, and may in places be
-at odds with conventions inside GnuCash code (and with general accounting
-principals... I am in no way an accountant), and thus may not be practical.
-However, I believe that they provide a self-consistent view of how
-one might do this, and I hope that this document will serve to continue
-the discussion that began on the GnuCash/Xacc mailing list.
-
-\section bugettoc tableofcontents
-
-\subsection budgetdefines Definitions
-
-As with any design paper, we'll need a few definitions. I'll try to
-stick as close to possible to the Xacc usage of these terms, but I'm
-not intimately familiar with the code, so I may have made some errors
-here.
-
-- Journal A journal is a simply a list of transactions with minimal
- characterization. For the purposes of this paper, the journal is
- defined to include only transactions that have already occurred,
- i.e., expected or up-coming expenses would not appear in the journal.
-- Calendar For the purposes of this paper, the calendar as a list of
- fully-defined future transactions, organized by date. A transaction
- would only appear in the calendar if there was a low likelihood
- that it would change. Future transactions that would only change
- by surprise (e.g. the cable TV bill) could appear in the calendar,
- but utility bills such as from the natural gas company would appear
- in the calendar only after receipt.
-- Template A template is in effect a partially defined transaction,
- possibly containing constraints. For example, one might have a template
- that would identify the price, payee, description, asset account
- and expense account (but not the date) for buying a Value Meal #4
- at the corner McDonald's, so every time you get the Value Meal #4
- you could pull it out of a GUI pick list and just specify the date.
- Alternatively, one could have a template that specified much of
- the data for the natural gas bill but not the amount, so that (a)
- entering the transaction when the bill came could be simplified,
- and (b) the partial information could be recorded, in effect as
- a reminder. A template could include such information as a confidence
- interval, so that, for example, if you and your family go out to
- dinner every Friday night and it usually costs $20-50, you could
- create a template that had $35 +/- $15 as the amount. Such templates
- could be extremely useful in making projections. Quicken, of course,
- has similar things called ``memorized transactions,'' but Quicken
- gives less control over their creation, meaning and use.
-- Schedule The schedule is a supplement to the calendar that contains
- only dated references to templates, which could be further narrowed
- as part of the reference, e.g. an undated template could be given
- a date but not a firm value when referenced from the schedule.
-- Ledger The ledger is in effect documentation of the journal, in that
- it describes the meaning of the transactions with respect to the
- balances in the various accounts. In Xacc, this appears also to
- be known as the register. It isn't clear to me that Xacc maintains
- the journal and the ledger separately. The ledger could easily be
- expanded to include documentation of the calendar transactions,
- but it is less clear that one would want to include the template
- references from the schedule directly in the ledger; it may make
- more sense for the schedule to be a ledger unto itself.
-- Budget A budget is an allocation of monetary flows. As funds enter
- the system through the income accounts, they must be transferred
- to other accounts; a direct deposit would be a transfer to an asset
- account, a loan payment through payroll deduction a transfer to
- a liability account, and tax withholding a transfer to an expense
- account. Of course, secondary transfers - check payments to credit
- card accounts, for example - are expected. The budget must cover
- a certain time period; one year is typical but not necessary. Typically
- one begins with the expected income over the budget period and describes
- what is expected to become of the money. In addition, it is typically
- the case that one will begin a budget period with initial assets
- and liabilities, that assets may be transferred to expense and liability
- accounts, and that new liabilities may be created as a way to obtain
- additional assets or cover expenses. It is not necessary and is
- in fact (in my view) undesirable for the budget to make specific
- reference to any transactions or templates; it is not even necessary
- to describe the precise path of the funds through accounts. Thus,
- while the budget documents one's goals for where the funds wind
- up, the schedule, calendar, journal and ledger describe the actual
- mechanics of the process. Finally, it should be noted that, in addition
- to describing the endpoints of the budget period, one typically
- will set a certain checkpoint frequency in the budget so that (a)
- the time dependence of the various flows is more obvious, and (b)
- one can conduct periodic verification of the accounts' status with
- respect to the budget. Most often this checkpoint frequency is either
- monthly or per-four-weeks. The former might be referred to as ``budgeting
- on a monthly basis.''
-
-\subsection budgetdocs Documenting the Budget
-
-One possible way to document a budget might be as a classic ``input-output
-table''. Consider the following table:
-\verbatim
-+---------+----------+---------+-----+------+------+-----+------+------+
-| | Checking | Savings | MMA | Cash | Visa | Tax | Food | Rent |
-+---------+----------+---------+-----+------+------+-----+------+------+
-+---------+----------+---------+-----+------+------+-----+------+------+
-|Checking | x | 3 | 2 | 7 | 3 | | | 5 |
-+---------+----------+---------+-----+------+------+-----+------+------+
-|Savings | | x | 1 | | | | | |
-+---------+----------+---------+-----+------+------+-----+------+------+
-| MMA | | | x | | | | | |
-+---------+----------+---------+-----+------+------+-----+------+------+
-| Cash | | | | x | | | 6 | |
-+---------+----------+---------+-----+------+------+-----+------+------+
-| Visa | | | | 8 | x | | 7 | |
-+---------+----------+---------+-----+------+------+-----+------+------+
-|Paycheck | 20 | | | | | 5 | | |
-+---------+----------+---------+-----+------+------+-----+------+------+
-|Interest | | 2 | 3 | | | | | |
-+---------+----------+---------+-----+------+------+-----+------+------+
-\endverbatim
-
-The first five data columns and the first five data rows have the same
-names. These are the asset and liability accounts. The last three
-columns are the expense accounts, and the last two rows are the income
-accounts (When I learn a little more SGML I'll try to make the table
-a little more readable). Notice:
-
-- If you sum across the income rows, you obtain the total income for
- each account: $25 from paychecks and $5 from interest, for a total
- of $30. If you sum down the expense rows, you obtain the total expenses
- for each account: $5 for taxes, $13 for food, and $5 for rent (OK,
- so we eat a lot). Just looking at these two figures, we can immediately
- see that we expect to make $30 and spend $23 of it.
-- The sense of each amount is positive from the row account to the
- column account. Thus, $20 of pay is direct-deposited to the checking
- account, and the remaining $5 is withheld for taxes. $1 is transferred
- from the savings account to the money market account. We plan to
- use the Visa card to buy $7 worth of food and to take a $8 cash
- advance. We also plan to pay Visa bills totalling $3 from the checking
- account.
-- If you sum down an asset/liability column, you will obtain the total
- amount we expect to add to that account (e.g. $6 added to the MMA,
- $20 added to checking, $3 to Visa). If you sum across an asset/liability
- row, you will obtain the total amount we expect to remove from that
- account (e.g. none from the MMA, $20 from checking, $15 from Visa).
- Thus, if you subtract the row sum from the column sum for a single
- asset or liability account, you may obtain the planned net change
- in that account for the budget period. Thus, we expect checking
- to be a wash, the MMA to grow by $6, and to go $12 further in the
- hole on our Visa card.
-- Again, what is documented here is the planned account-to-account
- flow across the entire period, not individual transactions.
-
-\subsection budgetcontrib Contributing Data
-
-(to be done)
-================================================================
-
-
-Where I'm headed for the rest of it is this:
-
-- I expect to point out that the Journal, Calendar and
- Ledger as I have described them are only tangentially
- related to the budget. They are the empirical data and
- the Budget and the Schedule are the models. The goal
- would be to have an engine that would allow one to
- measure the deviation of the empirical data from
- the model in various ways.
-- I expect to talk about the task of generating both
- the schedule and the budget. When one prepares this
- stuff, one usually has a rather diverse collection of
- data to work with. Bi-weekly paychecks, monthly
- interest income, quarterly dividends, five-day-per-week
- lunch charges, etc. What I would very much like to do
- is describe a mechanism whereby one could simply enter
- all these kinds of data into the engine, and it will
- digest it all into the budget and/or schedule formats.
- I expect to do this by preparing projected transactions
- as "templates", and then specifying a time series of
- instantiations of the templates.
-- I expect to describe a design for a sort of OO
- time series engine, where "time series" is a class.
- Instances of "time series" will have begin dates,
- end dates, frequencies, and the data series itself.
- Time series arithmetic will be defined, and these may
- entail frequency conversions to force the operand series
- to commensurate frequencies before combination. Thus,
- explicit conversion functions, say "monthly_to_daily"
- will need to be defined.
-- Once these pieces are in place, then one should be
- able to use the time series engine to digest the
- scraps of paper with scribbles saying "Katie's lunch,
- $2.30 every Monday through Thursday except only
- $0.40 on Friday because they have burritos on
- Friday and she hates them and brings her lunch but
- still needs milk" into something usable as a
- budget -or- as a schedule (these being two separate
- outputs).
-- While I expect that such an engine would be extremely
- useful for about 80% of the data that would go into
- a budget, there will of course be other data for which
- this would be overkill or cumbersome. Like "$85 each
- February and October for spraying the hemlocks with
- dormant oil". I can't imagine that anyone would rather
- make up some bogus time series for this than to open
- up a spreadsheet and type in two numbers, or even
- add a couple of records to an input data file. Thus, there
- should be some mechanism for this, where hand-entered
- data can be merged into the final budget or schedule.
- it should not, however, be implemented as hand edits to the
- draft table coming out of the time series engine,
- because one will want to be able to iterate on this.
-- Nonetheless, it probably remains true that users
- would wish to take the final budget output of all this
- automated stuff, and hack it up into something
- that somehow pleases them better. Thus it probably
- *does* make sense to allow hand edits at the final
- stage, and/or to simply enter an entire budget by
- hand if that is what you want to do.
-- So far, I don't see any simple way to implement
- something like Quicken's SuperCategories. Maybe this
- is related to why it works so poorly in Quicken. :-)
-
-*/
diff --git a/libgnucash/doc/constraints.txt b/libgnucash/doc/constraints.txt
deleted file mode 100644
index 9d3a928408..0000000000
--- a/libgnucash/doc/constraints.txt
+++ /dev/null
@@ -1,98 +0,0 @@
-/** \page financeconstraints Financial Constraints in GnuCash
-
- Linas Vepstas <linas at linas.org>
- September 2003
-
-
-\section financeoverview Overview:
-
-The GnuCash Engine implements a set of financial constraints so
-that a set of basic/core accounting rules are obeyed. The best
-known example is the "double-entry" constraint: the total value
-of a transaction must always be zero. A more mundane example
-is that cap gains are recorded on the date that they occur: or,
-more plainly: the posted date on the transaction that records
-cap gains is the same as the posted date of the transaction that
-caused the gains. At this time, these constraints are
-implemented in an ad-hoc manner. The goal of this document is
-to list and document as many of these constraints as possible,
-and to review the framework in which they operate. A possible
-future direction is to formalize the framework, so that it becomes
-easier to add and work with new types of constraints.
-
-
-\section financeintro Introduction:
-
-There are three very different classes of constraints within GnuCash,
-which should not be confused with each other. They work in very
-different ways and have very different goals. First, there are
-the "GUI Constraints", which are implemented as events: they make
-sure that the the GUI displays the data in the engine as it currently
-stands. Next are the "Multi-User Constraints", which are implemented
-in the Postgres SQL backend: They make sure that as one user alters
-data, that it is reflected in what the other users see. Finally,
-there are the "Financial Constraints", implemented in the engine,
-that make sure that the financial data recorded in the engine meets
-a set of core and extended accounting rules. This document deals
-primarily with this third class.
-
-Note that some financial constraints are so core, so key to GnuCash
-that they are woven into the object design itself. For example, the
-posted date is a part of the transaction: different splits cannot
-possibly have different posted dates, as there is no mechanism to
-represent this. All splits get their posted date from their parent
-transaction.
-
-The constraints that we are most interested in are the ones that
-are implemented as 'triggers' or 'scrubbers': these are not reflected
-in the core structure, but are rather implemented as routines that
-run at specific times and alter the data to be self-consistent in
-certain ways. The 'double-entry' constraint belongs to this class:
-it computes the total value of all the splits in a transaction, and
-adds one, if needed, to bring the total to zero. This constraint
-runs when the transaction is committed. Although this is an important
-constraint, there is no (easy) way to reflect it directly in the
-object design; thus, it acts as a rule that must be periodically
-imposed.
-
-At this time, the financial constraints within gnucash are impelmented
-in an ad-hoc manner, with no governing framework. This may change,
-as there is pressure to support more complex constraints that vary
-by region/country, by account type, by industry, etc.
-
-\section financelazy Why Not 'Lazy Evaluation'?
-
-Lazy evaluation is superficially like constraints, but differs in an
-important way. With lazy evaluation, when something changes (e.g.
-the posted date) it is marked dirty. Later, when something else needs
-something (e.g. the posted date on a gains split), the dirty flag
-is examined, and, if dirty, the new/corrected value is computed and
-returned.
-
-Simple/ad-hoc lazy evaluation works well when data dependencies are
-simple, but it breaks down when there are too many/circular
-relationships. It becomes all too easy to get trapped in infinite
-loops of corrections. The goal of moving to a formal constraint
-system is to introduce specific, well-defined sync points where
-constraint checking can be done, without incuring circular
-deopendencies. At this time, the sync point is the xaccTransCommitEdit()
-subroutine.
-
-\section financelist List of Constraints
-
-The following is a list of the constraints that are currently
-implemented in the GnuCash Engine, with a short description of what
-they are, and how they work.
-
-- Double Entry
-- Double-Balance
-- Date Posted of Gains Transaction
- The posted date of the gains transaction is kept in sync with the
- posted date on the transaction that is the source of the gains.
- See the document 'lots.txt', section 'Cap Gains Actual Implementation'
- for details.
-- Value of Gains Transaction
- The value recorded by the gains transaction is kept in sync with
- the value
-
-*/
diff --git a/libgnucash/doc/currencies.txt b/libgnucash/doc/currencies.txt
deleted file mode 100644
index def872672d..0000000000
--- a/libgnucash/doc/currencies.txt
+++ /dev/null
@@ -1,58 +0,0 @@
-/** \page currencies Currency Issues
-
-API: \ref Commodity
-
-From Bill Gribble <grib at billgribble.com>
-Tue, 3 Oct 2000 11:09:54 -0500
-
-We need to fix a single way of dealing with this that
-addresses all of the concerns. Maybe we should list the
-problems/requirements to make sure we are talking about the same
-thing. I know I've repeated several times that I believe the
-"eliminate Currency accounts" problem-set is separable from the
-"global A=L+E" problem-set; I'll list them all together here, because
-I think it's just a "feature" of some particular solutions that they
-are separable.
-
-- we want to eliminate the need for currency trading accounts. From
- a user interaction perspective, this means we need to allow
- transfers directly between accounts denominated in different
- commodities.
-- we want transactions to have clear and unambiguous balancing
- semantics.
-- we want to store the actual amounts of commodities involved
- transactions rather than price and quantity.
-- we want to be able to globally check and display the terms of the
- accounting equation (and all account balances) in a
- user-selectable functional currency.
-
-I think the following bits will address the first three issues above.
-Basically I'm just agreeing with your last suggestion, Dave; Rob and I
-hammered on it on a white board and weren't able to poke any holes.
-
-- Eliminate the 'currency' from the Account structure. Add a
- 'currency' to the Transaction structure. Each transaction's
- 'currency' is by definition the balancing common currency for the
- splits in that transaction.
-
-- Eliminate the 'share price' field from the Split structure and
- replace it with a 'value' field. The 'value' is a translation of
- the Split's 'damount' (which is the amount of the Account's
- security involved) into the Transaction's balancing currency.
-
-The balancing semantics of this approach are unambiguous, no existing
-balanced gnucash transactions would be disallowed (the transaction's
-common currency just gets saved in a pointer) and the fuzzy
-distinction between the account's currency, security, damount, value
-is cleared up.
-
-About the last point, the global accounting equation. Evaluating this
-equation requires the computation of current asset values and
-unrealized gains/losses. I believe this is possible in a
-straightforward way using the reporting framework, a user-selectable
-functional currency, accepted accounting policies, and a historical
-price database. There has been discussion about moving to a
-report-based main window; if that were to be the case, we could make
-the accounting equation readily visible to the user.
-
-*/
diff --git a/libgnucash/doc/doxygen_main_page.c b/libgnucash/doc/doxygen_main_page.c
index d50603987e..5454ff5eea 100644
--- a/libgnucash/doc/doxygen_main_page.c
+++ b/libgnucash/doc/doxygen_main_page.c
@@ -30,28 +30,12 @@ src/doc/design, but this is even more outdated.
Where possible, each overview is dated - take care to review older texts
in relation to existing code.
-- \ref backuppolicy
-- \ref bookperiods
-- \ref currencies
- \ref deprecated
-- \ref engine
-- \ref backendold
-- \ref financeconstraints
-- \ref druidframework
-- \ref guid
-- \ref gnome2
- \ref loanhandling
- \ref kvpvalues
- \ref lotsoverview
-- \ref multicurrency
-- \ref pricedocs
-- \ref gnucashextension
- \ref python_bindings_page
-- \ref qif
-- \ref budgetplan
-- \ref taxnotes
- \ref todo
-- \ref userprefs
Each overview in this section is generated directly from the
source files using Doxygen but some topics need updating.
diff --git a/libgnucash/doc/engine.txt b/libgnucash/doc/engine.txt
deleted file mode 100644
index 437e443557..0000000000
--- a/libgnucash/doc/engine.txt
+++ /dev/null
@@ -1,45 +0,0 @@
-/** \page engine Engine Framework
-
-API: \ref Engine
-
-Additional engine API documentation can be found in the src/doc/design/engine.texinfo file.
-
-This file contains some extra meta-information that is not directly relevant
-to the API documentation.
-
-\section firstclass First Class Objects (C structs) vs. Storing Data in KVP Trees
-
-API: \ref KVP
-
-Suppose you have a neat idea for a new feature for the GnuCash engine.
-Should you create a C structure (a "first class object") and all
-of the required machinery for it (e.g. an SQL backend), or should you
-just put all of the data in a suitable KVP (Key Value Pair) frame
-somewhere?
-
-The answer depends on whether the concept requires extensive
-pointer chasing between different types of existing C structs,
-or whether it more naturally can hang with some existing object.
-
-If it seems to be an independent concept, it can still be placed
-in the KVP tree of the book, which gives it a 'top-level' existence.
-
-If the concept is used only infrequently, then it probably belongs
-in a KVP tree. If the concept has performance-critical requirements,
-then it is better to implement it as a C struct, and similarly
-design an appropriate SQL table around it, so that the database
-can be queried efficiently and rapidly.
-
-\subsection terms Terminology:
-
-- First-class object: something that has a C struct associated with it,
-and has its own specialized backend infrastructure for storing/querying
-it.
-
-- Second-class object: something that lives entirely in a KVP tree.
-Note, however, that not all data in a KVP tree deserves to be called
-an 'object'. Some things in a KVP tree are merely 'attributes'.
-If you push on this point, there is indeed a gray area between
-second-class objects and attributes.
-
-*/
diff --git a/libgnucash/doc/g2-architecture.txt b/libgnucash/doc/g2-architecture.txt
deleted file mode 100644
index 64790d698b..0000000000
--- a/libgnucash/doc/g2-architecture.txt
+++ /dev/null
@@ -1,161 +0,0 @@
-/** \page gnome2 GnuCash Gnome2 architecture
-
-\section gnome2names Naming
-
-g1 - The gtk1 and gnome1 libraries.
-
-g2 - The gtk2 and gnome2 libraries.
-
-\section gnome2primer GTK2 Primer
-
-In gtk2, an "action" is a g_object that represents some action that
-the user might want to perform. This object could represent opening a
-file, toggling the toolbar, etc. The action itself has *no* gui
-component. There is no way to directly display an action to the user.
-To do that, you assign the action to one or more proxy items. These
-proxy items are the regular menu items, toolbar buttons, etc. that you
-are familiar working with. There are several advantages to this new
-system. The first is that you no longer have to write multiple action
-routines; one for a menu selection and another for a button click.
-There is a single code fragment written for when the action fires,
-regardless of how it fired. The second advantage is that you no
-longer have to enable/disable the individual menu items and buttons.
-Enabling/disabling the action itself causes all proxy items to assume
-the same state. For example, if an account isn't selected in the
-account tree window, a single function call disables the "Open
-Account" command in the main application menus, the "Open Account"
-popup menu command, and the "Open Account" toolbar button.
-
-A gtk2 "menu merge" takes descriptions of two sets of menus and merges
-them into a single menu that is displayed on the screen. The first
-menu must contain attachment points in it. These attachment points
-are specified in the seconds set of menus and control where in the
-combined menu the items from the second menu appear. This second
-"merged" set of menus can easily be removed at any time.
-
-Gtk2 has deprecated the clist and ctree widgets. The replacement is a
-combination of a GtkTreeModel/GtkTreeView pair of objects.
-
-In G1, most objects were based on a gtk_object, and were created,
-destroyed, signaled, etc. using functions on this base object. In g2
-the base object was moved from gtk2 to glib2, so most objects now need
-to be based on the g_object object. There are still compatibility
-functions on in gtk_object but you cannot mix and match calls to
-g_object and gtk_object. You must use one function set or the other
-for any given item.
-
-\section gnome2windows Windowing Architecture
-
-In the gtk1/gnome1 (hereafter g1) version of Gnucash, the windowing
-was based on the "Multiple Document Interface" of g1. This code was
-hard to use in the first place, and has been deprecated in g2.
-
-The g2 version of gnucash is a series of plugin modules designed
-around the g2 concepts of "actions" and "menu merging". These
-concepts will be integrated into gtk2.4 release.
-
-The first level of this architecture is an object representing a
-"pluggable" window. This object is responsible for:
-
--# the window itself
--# providing a framework for plugins
--# providing a base set of menus (and actions)
-
-Plugins can be one of two types. The first type is simply called a
-"plugin" (e.g. gnc-plugin-register.c) and is used to add functionality
-to the base window. This plugin provides only a menu/toolbar
-description, and a way to create the second type of plugin. The
-second type of plugin is called a "plugin page"
-(e.g. gnc-plugin-page-register.c) and provides both a menu/toolbar
-description, but also a widget that is displayed in the containing
-window. This widget may be an account tree, a register, etc. The
-plugin page must also provide a standard set of functions to interact
-with the plugin manager code.
-
-\section gnome2model Model/View Architecture
-
-API: \ref GuiTreeModel
-
-As mentioned above, the ctree widget has been deprecated in g2. Some
-parts of gnucash have been converted to the new style using either a
-GtkTreeModel/GtkTreeView pair of widgets, or using a
-GtkTreeModel/GtkTreeModelFilter/GtkTreeModelSort/GtkTreeView set of
-stacked widgets. The account tree is presented here as example of the
-latter.
-
-In gnucash, all the accounts are stored in the engine. The account
-tree "model" (a GtkTreeModel) provides a representation of these
-accounts that can be used by one or more views presented on the user's
-screen. This code is designed so that there is only one single model
-for the accounts in a given book, and this single model drives all
-views. (This code should be easily expandable to multiple sets of
-books once engine support is added.) The filters and views are
-completely independent of each other, even though they share a common
-model, so you may see different accounts in each view, have different
-accounts selected in each view, etc.
-
-The account tree model is designed as a tree and contains a "pseudo"
-account that is the root node of this tree. Whether the root node is
-visible is a per-view setting. Also in the model is code to display
-the contents of any row/column intersection in the tree. The
-GtkTreeView code drives the actual display, and pulls numbers from the
-account tree model as necessary to display them. For all intents and
-purposes, the model is the sole gui representation of the account
-tree. The overlaying filters and views simply limit what the user
-sees to some subset of the information in the model. There are very,
-very few instances where code interacts directly with the account tree
-model. All interaction should be done through the account tree view
-described later.
-
-The next layer in the account tree is the GtkTreeModelFilter. This
-filter is automatically created when the account tree view is created.
-In most instances, this filter is used to install a "virtual root" on
-the model that hides the top level "pseudo" account from the user. At
-the time of this writing, only the account edit dialog leave this top
-node visible (so the user can create a new "top level" account.) This
-filter level is use in several places to install a visibility filter
-onto the model, controlling which accounts are visible to the user and
-which are hidden. These visibility decisions are made in real time as
-the user clicks the disclosure triangle on an account to see what
-sub-accounts it contains. This callback function for the visibility
-filter is the only place where the code should interact directly with
-the account tree model, and the only interaction should be to take the
-provided model/iter pair and ask the account tree model for the
-corresponding account. After that the callback may do whatever it
-wants on the account and then return TRUE if it wants the account to
-be visible, FALSE if not.
-
-The next layer in the account tree is the GtkTreeModelSort. This
-layer provides the capabilities needed by a GtkTreeView to allow
-sorting by clicking on column headers. If a column has a
-non-alphanumeric sort, the GtkTreeView implementation must provide a
-sort function for each different type of sort. This function will be
-called by the GtkTreeSortModel for each pair of items it needs to
-sort. The account tree model provides seven different sort functions
-that are used by various columns.
-
-The top layer of the account tree is the account tree view. The
-underlying GtkTreeView object provides all the standard tree
-manipulation functions; opening accounts to see sub-accounts, selecting
-an item, etc. The account tree view is the programming interface that
-should be used to manipulate an account tree. It provides the
-functions to create a new view, to set a filter on an existing view to
-control the visible rows, to configure the columns visible in the
-view, to get/set the selected account(s) in the view, etc. There is
-also a selection callback function available from the view, that may
-be used to decide whether or not the user can select an account in the
-view. It is used in the new account dialog, for instance, to limit
-the accounts the user may select for the opening balance to an account
-that has the same currency as the account being created.
-
-\section gnome2ref References
-
-http://developer.gnome.org/dotplan/porting/index.html
-
-http://developer.gnome.org/doc/API/2.0/glib/index.html
-
-http://developer.gnome.org/doc/API/2.0/gobject/index.html
-
-http://developer.gnome.org/doc/API/2.0/gtk/index.html
-
-*/
diff --git a/libgnucash/doc/generic-druid-framework.txt b/libgnucash/doc/generic-druid-framework.txt
deleted file mode 100644
index d70b32e958..0000000000
--- a/libgnucash/doc/generic-druid-framework.txt
+++ /dev/null
@@ -1,300 +0,0 @@
-/** \page druidframework Generic (Import) Druid Framework
-
- Derek Atkins <derek at ihtfp.com>
- 2004-01-12
-
- Work in progress
-
-\section druidbackground Background
-
-The GNOME Druid infrastructure wants to force you to be UI-driven.
-What this means is that the druid is started and lives in gtk_main()
-while the user responds to the displayed Druid page. When the user
-clicks a button (Next, Back, Help, or something inside the Druid page)
-it performs some operation and then returns control to the GUI. For
-example, a user clicking "Next" forces a callback based on that
-specific page. That callback can (and should) set the next druid page
-before returning control to the GUI.
-
-If we were to make the importer backend-driven instead of GUI-driven
-we would necessarily require nested gtk_main()'s. The reason is
-that the backend was originally executed from GUI callback, so what
-should happen is that the initialization sets up the import process
-and then returns control so we dont have a nested gtk_main().
-
-Nesting gtk_main() can result in crashes. If the originating window
-is destroyed then when control returns we've jumped back into invalid
-data space. This has happened on numerous occasions within the
-gnucash code over time and has caused numerous bugs. For example, the
-'Save while saving crashes gnucash' bug was due to a nested gtk_main
-caused by the progress-bar. Consequently, the best way to avoid this
-problem is not to introduce this problem and avoid nested gtk_main()
-whenever possible. This means the importer should be GUI-driven, not
-backend-driven.
-
-\section druidproblem The Problem
-
-For a generic importer druid, we want to create a single druid (or set
-of druid components) that all importers can use. Moreover, this
-framework should be UI-widget independent. The problem is that
-different importer backends have different requirements for the UI.
-For example, the QIF importer needs to map QIF Categories to GnuCash
-Accounts, but OFX or HBCI have no such mapping requirement.
-
-Another issue is that some sub-processes of the importing process
-require multiple druid pages. If this sub-process is repeatable, it
-means the druid needs to be able to jump back to the beginning of the
-sub-process. For example, the process to choose files to import
-should allow users to import multiple files at one time.
-
-Moreover, even when a backend may sometimes require access to
-particular druid sub-process, it may need to skip that sub-process
-sometimes. For example, the QIF importer may have an ambiguity in the
-date format for a file, requiring the user to choose the actual date
-format. However if the imported file is not ambiguous this
-sub-process of the druid can be skipped.
-
-All of this means the druid framework should be able to rotate across
-a subset of the pages for a sub-process or skip pages for a
-sub-process based on the requirements of the backend.
-
-In addition the framework should allow a global setting to enable or
-disable "documentation pages" (c.f. the Show QIF Documentation
-preference). Each sub-process can have a set of doc pages available
-which can be displayed (or not) based on a user preference.
-
-\section druidmain The Druid Framework
-
-In order to refrain from pulling Gnome and GTK into the backend
-implementations, we need a GUI-independent UI framework for Druids.
-The framework is broken into Providers and the Druid Builder. A
-Provider supplies a set of druid pages and the appropriate callbacks
-for the backend to retrieve the user's data. The Druid Builder is the
-process the backend uses to combine the various Providers into the
-ultimate druid and set up all the callbacks to properly hook the druid
-and backend together.
-
-Each provider implements the Provider API and Provider Registrar API
-and registers itself with the druid provider registry. The Provider
-Registrar API defines the minimal set of functions and methods to
-instantiate a provider and place a set of one or more pages into a
-druid instance. The Provider API is used to set up the callbacks to
-hook that provider into the backend.
-
-In addition to the standard Provider API, each provider must define a
-private API for use with the backend. Each provider is going to
-interact with the backend differently, so there is no way to define a
-common API for this interaction. On the other hand, the backend
-already knows a priori which providers it needs to use, so it can know
-the provider-dependent API and use that interaction.
-
-The druid provider registry allows the Druid Builder to combine the
-providers in the requested order when a backend asks to build a druid.
-It uses the Provider Registrar API to instantiate a Provider and hook
-it into the Druid, and then uses the Provider API to connect the
-Provider to the backend using the data provided by the backend.
-
-This leaves the importer backend blissfully unaware of the actual
-Druid GUI/toolkit implementation (i.e. it doesn't need to know that
-the Druid is actually a GnomeDruid -- it could be some other UI
-toolkit). The backend calls the Druid Builder to put together the
-druid with the appropriate providers and supplies the
-provider-specific callback information necessary to hook into the
-druid.
-
-In order to initiate an import for a particular backend, the GUI calls
-into the "start import" routine which builds an import context, builds
-the import druid, and then returns control let the GUI run. This
-means the import backend should be completely callback-based,
-including the cleanup code in case the user interrupts the import.
-
-\section druidprocess Druid Sub-Process Providers
-
-In order to abstract the Druid from the various importer backends, the
-import process is broken into a set of sub-processes. Each
-sub-process is implemented as a Provider in the Druid framework. The
-Provider implements a set of Druid pages that can be added to the
-running druid and provides a set of callbacks to supply that input to
-the import backend. For example, one sub-process could be "select the
-file(s) for import" and another is "choose the date/number format".
-
-The interface between the Provider and the Builder is obviously
-toolkit-specific because the builder need to piece together the actual
-druid pages (e.g. GnomeDruidPageStandard). The druid builder requests
-an instance of a provider (and its pages) and supplies the provider
-with the backend callbacks requests. The provider instance creates
-the druid pages and connects the passed-in callback data so it can
-call the backend appropriately.
-
-Each provider necessarily requires its own callback interface (because
-each provider needs to supply different data to the backend in
-different ways). This is implemented by subclassing the basic
-callback storage type. Because the importer backend knows the
-providers being used, it can provide the required callback storage
-type when it builds the druid.
-
-When a user fills in a druid page and clicks on "Next" the druid will
-call the next-page callback and supply the provided data (as defined
-in the particular provider callback API). The backend then acts on
-the callback data, sets the next page in the druid, and returns
-control. Similar operations occur when the user clicks "Back", a
-back-page callback, or any other callbacks required by the specific
-provider.
-
-\section druidtogether Putting the Druid Together
-
-In order to build the druid, the import backend builds the list of
-providers and passes that list to the Druid Builder. The Builder
-creates the base druid and then pulls the druid pages from each
-provider and inserts them into the druid. Finally, the builder
-displays the druid and starts the process.
-
-\section druidbackend Linking into the Backend
-
-When supplying the list of providers to the builder, the backend also
-provides a set of callbacks. Since the backend knows what providers
-it wants, it can set up the appropriate callbacks. Each callback,
-when called, passes in the user-input data in the callback function.
-The callback function should process the data, set the next druid
-page, and then return.
-
-\section druidcore Core GncDruid Types
-
-\subsection druidpage GncDruidPage
-
- Opaque (toolkit-specific) type: a druid page. Used to pass an
- opaque object from the provider, through the backend, to the druid
- system (e.g. in order to set the druid page).
-
-\subsection druidcallback GncDruidCB
-
- Base type of a druid callback. Minimum information is the backend context.
-
- Members:
-
- gpointer backend_ctx;
-
-\subsection druidobject GncDruid
-
- The context object of a druid. This object contains all the
- necessary data to maintain the druid and reference all it's data.
-
- Members:
-
- void set_page(\n
- GncDruid,\n
- GncDruidPage);
-
- Set the current page of the druid to the GncDruidPage.
-
- GncDruidProvider current_provider;\n
- GncDruidProvider (*next_provider)(GncDruid);\n
- GncDruidProvider (*prev_provider)(GncDruid);
-
-\subsection druidproviderdesc GncDruidProviderDesc
-
- The Druid Provider Description base class. This defines the minimal
- information to name a provider and provide the interface required to
- connect the provider to the backend. Each provider description
- implementation should subclass this type. The backend should use
- the subclasses.
-
- Members:
-
- const gchar *name;\n
- gboolean (*provider_needed)(GncDruidCB);\n
- gboolean (*next_cb)(GncDruid, GncDruidCB);\n
- gboolean (*prev_cb)(GncDruid, GncDruidCB);
-
-\subsection druidprovider GncDruidProvider
-
- An instance of a Druid Provider. Still toolkit-independent (a
- toolkit-specific subclass actually implements the functions
- necessary for the builder) this interface allows the backend to
- interface to the Provider to walk through the provider pages.
-
- Members:
-
- GncDruidPage (*first_page)(GncDruidProvider);\n
- GncDruidPage (*next_page)(GncDruidProvider);\n
- GncDruidPage (*prev_page)(GncDruidProvider);
-
-\section druidapi The Druid Builder API
-
-GncDruid gnc_druid_build(\n
- GList *providers,\n
- gpointer backend_ctx,\n
- void (*end)(gpointer))
-
- Build a druid using the supplied list of providers descriptions
- (GncDruidProviderDesc). The provider list also contains all the
- callback information necessary to hook the backend into the druid.
- The backend_ctx and end() parameter are used to end the session in
- the case of the user clicking "cancel". It cleans up the backend
- context.
-
-\section druidinternal The Basic (internal) Provider APIs
-
-GncDruidProvider gnc_provider_get_instance(\n
- GncDruid druid_ctx,\n
- GncDruidProviderDesc description,\n
- gpointer backend_ctx)
-
- Obtain an instance of a Druid Provider based on the Provider
- Description. This is used by the druid builder to obtain a Provider
- Instance given the Provider Description.
-
-void gnc_provider_register(\n
- const gchar* name,\n
- gnc_provider_get_instance);
-
- Register a Provider Implementation of the provided name. Provide a
- creation function that gnc_provider_get_instance() can use to obtain
- a fully initialized provider object.
-
-\section druidproviderapi Specific GncDruidProviderDesc APIs
-
-Each provider needs to create its own subclass of GncDruidProviderDesc
-that defines its specific interface to the backend. The following
-sections show some example interfaces. In addition to the
-ProviderDesc object, each provider can also provide a subclassed
-GncDruidCB object for use in the callbacks.
-
- GncDruidProviderDescChooseFmt
-
- A provider that allows the user to choose a format in the case of
- ambiguous input.
-
- Members:
-
- void (*get_ambiguity)(\n
- gpointer be_ctx,\n
- GncImportFormat* choices,\n
- GncImportFormat* last_choice);
-
- GncDruidChooseFmtCB
-
- Members:
-
- GncImportFormat choice;
-
-
- GncDruidProviderDescSelectFile
-
- A provider that allows the user to select the file(s) to import.
-
- Members:
-
- gboolean multi_file;\n
- gchar* last_directory;\n
- GList * (*get_files)(gpointer be_ctx);\n
- const gchar* (*get_filename)(GncImportFile file);\n
- void (*remove_file)(gpointer be_ctx, GncImportFile file)
-
- GncDruidSelectFileCB
-
- Members:
-
- gchar* filename;
-
-*/
diff --git a/libgnucash/doc/gnc-numeric-example.txt b/libgnucash/doc/gnc-numeric-example.txt
deleted file mode 100644
index a2e04cb972..0000000000
--- a/libgnucash/doc/gnc-numeric-example.txt
+++ /dev/null
@@ -1,48 +0,0 @@
-/** \page gncnumericexample gnc_numeric Example
-
-\section example EXAMPLE
-
-The following program finds the best ::gnc_numeric approximation to
-the \a math.h constant \a M_PI given a maximum denominator. For
-large denominators, the ::gnc_numeric approximation is accurate to
-more decimal places than will generally be needed, but in some cases
-this may not be good enough. For example,
-
- at verbatim
- M_PI = 3.14159265358979323846
- 245850922 / 78256779 = 3.14159265358979311599 (16 sig figs)
- 3126535 / 995207 = 3.14159265358865047446 (12 sig figs)
- 355 / 113 = 3.14159292035398252096 (7 sig figs)
- at endverbatim
-
- at verbatim
-#include <glib.h>
-#include <qof.h>
-#include <math.h>
-
-int
-main(int argc, char ** argv)
-{
- gnc_numeric approx, best;
- double err, best_err=1.0;
- double m_pi = M_PI;
- gint64 denom;
- gint64 max;
-
- sscanf(argv[1], "%Ld", &max);
-
- for (denom = 1; denom < max; denom++)
- {
- approx = double_to_gnc_numeric (m_pi, denom, GNC_RND_ROUND);
- err = m_pi - gnc_numeric_to_double (approx);
- if (fabs (err) < fabs (best_err))
- {
- best = approx;
- best_err = err;
- printf ("%Ld / %Ld = %.30f\n", gnc_numeric_num (best),
- gnc_numeric_denom (best), gnc_numeric_to_double (best));
- }
- }
-}
- at endverbatim
-*/
diff --git a/libgnucash/doc/guid.txt b/libgnucash/doc/guid.txt
deleted file mode 100644
index 5c28093ac4..0000000000
--- a/libgnucash/doc/guid.txt
+++ /dev/null
@@ -1,60 +0,0 @@
-/** \page guid Globally Unique Identifiers: Design Issues
-
- Linas Vepstas November 2003
-
-API: \ref GUID
-
-\section guidsummary Summary
-
-GUID's are meant to uniquely identify a GnuCash object. However,
-when that object is backed up (by copying a gnucash data file),
-the identified object is no longer unique. Book closing is a
-formalized means of saving older data. If a GnuCash data set
-is large, and SQL is the storage backend, then making copies
-of old data can be very wasteful of storage space. However,
-book closing, by definition, must retain a copy of the data
-'as it once was', as an (auditable) historical record. This
-document debates different alternate schemes resolving the
-uniqueness, searchability, copies and storage-space issues
-that come up when handling GUID's on book closing.
-
-\section guidintro Introduction
-
-GUID's are meant to be a way of identifying a given GnuCash entity.
-Accounts, transactions, splits, prices and lots all have GUID's.
-GUID's can be used as a reference: by knowing a GUID, the matching
-entity can be found. Because GUID's are 128 bits long, one could
-have a billion different GnuCash users in a million different solar
-systems without worrying about accidentally assigning the same
-GUID to two different objects. So, given a GUID, one should be able
-to come up with the object uniquely identified by it, right?
-
-One practical problem is that backup copies of files containing
-GnuCash data will have the same GUID's as the 'live data'. Because
-the user may have modified the object, if one looked at the backup
-copy, one would find more-or-less the same object, but it might
-have different values (for the amount, the value, the date, the
-title, etc.) Thus, a single value for a GUID can be associated
-with several different but similar 'objects'.
-
-A related practical problem occurs with the 'closing of books',
-which is a certain formalized way of making a kind of backup.
-After one has accumulated a lot of financial data, one has to
-periodically make a permanent record of that data, and then
-weed through it to throw away old (no longer interesting)
-transactions. The 'closed book' contains all of the old
-transactions, while the 'open book' looks just like it (has the
-same accounts, etc), but doesn't have the old transactions.
-
-\section guidissue The Issue
-
-The current book-closing code makes a copy of the account tree,
-and sorts all transactions, by date, into the new or the old
-account tree. With the goal of not confusing the new and the
-old account trees, the book closing code issues the old accounts
-a new set of guids. The Pro's & Con's of this scheme:
-
-Pro: The 'old', closed accounts can be uniquely accessed according
-to their GUID's, without causing confusion with similar/same.
-
-*/
diff --git a/libgnucash/doc/multicurrency-discussion.txt b/libgnucash/doc/multicurrency-discussion.txt
deleted file mode 100644
index 4685a8cd4f..0000000000
--- a/libgnucash/doc/multicurrency-discussion.txt
+++ /dev/null
@@ -1,281 +0,0 @@
-/** \page multicurrency Multicurrency Discussion
-
-<cstim> goonie: well...
-
-<goonie> How about this:
-
-<cstim> goonie: You can print each value as a gnc-monetary
- goonie: this?
-
-<goonie> cstim: don't worry, go on with your outline.
-
-<cstim> How are you printing balances right now?
- I guess you plug a \a gnc-numeric into the html code.
- If you do a s/\a gnc-numeric/\a gnc-monetary/
- ... then everything would be multi-currency compliant
- Of course the \a gnc-monetary needs the actual currency specified.
- Would that lead to problems?
-Definition of \a gnc-monetary is in src/scm/gnc-numeric.scm
-
-<goonie> Cool.
-
-<cstim> Right now every \a gnc-monetary is printed like $500.23, DEM 123.45, CHF 456.32
-
-<goonie> I think that should work fine.
-
-<cstim> but the formatting of \a gnc-monetary could be modified by any style sheet.
-
-<goonie> You also had some code for calculating totals in multiple currencies?
-
-<cstim> goonie: ouch. Yes. But that gets complicated quickly.
-
-<goonie> Yes, it does.
-
-<cstim> goonie: You will need to use a commodity-collector from report-utilities.scm
-
-<goonie> OK, cool, I think I can figure it out.
-
-<cstim> If you want the total of only one commodity, you can use the 'getpair action of commodity-collector...
- but if you want to show (correctly) all of the currencies, you will have a lot of trouble.
- Basically, I have the "reference implementation" in html-utilities.scm .
-
-<goonie> OK, excellent.
-
-<cstim> You can see how I print just one balance...
- in the big function \a gnc:html-build-acct-table, line 297, where I print the total sum.
- That would be a starting point to see how a balance with a bunch of commodities gets printed.
-
-<goonie> cstim: taking it up a level for a second, how would you prefer a total for a
-collection of splits in different currencies to be displayed?
-
-<cstim> what do you mean by "total for splits"?
-
-<goonie> OK, consider a transaction report for the account Expenses:Beer for the period
-1/1/2001 to 2/1/2001 (UK date format ;)
- and let's say I've had beer in Australia, the US, Germany, and Hong Kong during that period.
- further, let's assume that my "native currency" is AUD.
- cstim: try some of the Australian specialty beers.
-
-<cstim> yes
-
-<goonie> cstim: but even VB or Carlton Draught is an improvement on soap suds . . . er, Budweiser.
- but back to Gnucash matters . . .
-
-<cstim> yes
-
-<goonie> now there's several possibilities for doing the totals here . . .
-
-<cstim> wait wait
- what accounts and what splits are you thinking of?
- or in other words, what are your sorting/account/viewing parameters?
-
-<goonie> Only one account selected, sorted by date, say (we'll discuss subtotals in a sec).
-
-<cstim> goonie: One account means that there is only one currency, right?
-
-<goonie> dave_p: hang on, let me just check . . .
- s/dave_p/cstim
-
-<cstim> oh
-
-<goonie> dave_p: what's the status of currency-in-transaction?
-
-<cstim> s/dave_p/???/
-
-<goonie> nope, really dave_p this time :)
-
-<cstim> dave_p is away: I'm doin' stuff
- AFAIK an account has a commodity and a transaction has a commodity.
-
-<goonie> correct.
-
-<cstim> \a gnc:account-get-commodity, \a gnc:transaction-get-commodity
-
-<goonie> However, read the comments in TransactionP.h
-\verbatim
- * The common_currency field indicates the currency type that
- * all of the splits in this transaction share in common. This
- * field is going to replace the currency field in the account
- * structures.
-\endverbatim
-
-<cstim> yeah, that's right.
-
-<goonie> So, in the short term, your assumption is correct.
- In the long term, not the case.
-
-<cstim> What I would usually call the "currency" of an account is in Gnucash acctually called "security".
-\a gnc:account-get-commodity will return this security of the account.
-
-<goonie> Gotta love terminology.
- The reason for the differentiation is for stock/mutual fund accounts, if I recall correctly.
-
-<cstim> The more recent comments about commodities are in Transaction.h, line 229 ff.
- or Account.h, line 203ff.
-
-<goonie> Yep, so the situation I described above can't happen right now, but will be possible
-in the near future. Which brings us back to how should we display things:
- A total for each currency.
-
-<cstim> What account would that be?
-
-<goonie> The account Expenses:Beer.
-
-<cstim> What security will it have?
-
-<goonie> AUD
-
-<cstim> okay.
-
-<cstim> go ahead
-
-<goonie> OK, say that there's only four transactions in that account for the period in question:
- $2 in AUD, 5 USD, 1 EURO, and 12 HKD being the values. What should we display as the total(s)?
- Or more to the point, what options do we need to offer?
-
-<cstim> waitwait. Expenses:beer has security AUD.
- So there is one Transaction between Cash:USD and the beer.
- And one between Cash:Euro and the beer.
- And one between (what the heck is) Cash:HKD and the beer.
-
-<goonie> Hong Kong Dollar, BTW.
-
-<cstim> And, say, those Transaction have the transaction-commodity according to the Cash:*
-
-<goonie> yep.
-
-<cstim> But the split which belongs to Exp:Beer has only one value
- and that value represents the beer expense in AUD.
- i.e. in the split's account's security.
-
-<goonie> hang on . . . let me think this through carefully . . .
-
-<cstim> ok, lets get things straight: Each split has two fields, value and damount
- Quote from a grib posting last October:
-\verbatim
- - Eliminate the 'share price' field from the Split structure and
- replace it with a 'value' field. The 'value' is a translation of
- the Split's 'damount' (which is the amount of the Account's
- security involved) into the Transaction's balancing currency.
-\endverbatim
- the last sentence is the one that matters.
-
-<goonie>
-\verbatim
- * value is the amount of the account's currency involved,
- * damount is the amount of the account's security. For
- * bank-type accounts, currency == security and
- * value == damount.
- gnc_numeric value;
- gnc_numeric damount;
-\endverbatim
- from src/engine/ TransactionP.h
-
-<cstim> that's outdated.
- In the long run: value is the amount of the transaction-commodity involved, damount is
-the amount of the account-commodity involved.
-
-<goonie> OK, but the value returned from \a gnc:split-get-value is the value rather than the damount.
- sorry for the long delay, I was reading code to make sure I understood what was going on.
- value being the one denominated in the transaction-commodity.
-
-<cstim> That's right. \a gnc:split-get-value gives you the value, whereas
-\a gnc:split-get-share-amount gives you the damount
- Maybe that functions need some name change in the future.
-
-<goonie> perhaps.
- the trouble is that there are so many things that need names in gnucash, that you start to run out :)
-
-<cstim> :)
- We could \a gnc:split-get-share-amount => \a gnc:split-get-damount
- whatever. My point for the Beer is let's have some.
-
-<cstim> oops.
- I would expect that the transaction report uses \a gnc:split-get-share-amount
- which in this case gives you already the amounts exchanged into AUD and everything's fine.
-
-<goonie> You would prefer that over the transaction-specific value, then?
-
-<cstim> Well, if I want the list for one specific account, then I would expect all amounts to be
-in that account's commodity, i.e. the account-commodity (formerly known as security :)
-
-<goonie> yep.
- But then the problem just arises in a different light if you have multiple accounts, sorted by date, say.
-
-<cstim> I would recommend a name change for \a gnc:split-get-share-amount.
- multiple accounts. okay, let's talk about that. what scenario do you think of?
-
-<goonie> cstim: could you mail Dave wrt function renaming?
-
-<cstim> I'll send a mail to the ML
-
-<goonie> OK, let's say you've selected Expenses:Champagne (in Francs), Expenses:Saki
-(in Yen), and Expenses:VB (in Aussie dollars), and you want a report for all those transactions
-for the past month, sorted by date. You have Cash:Francs, Cash:Yen and
-Cash:Aussie accounts with the expected currencies.
-
-<cstim> what's VB?
-
-<goonie> Victoria Bitter (Australian Beer).
-
-<cstim> okay. well...
-
-<goonie> If you want a distinctively Australian Alcoholic beverage, s/VB/Sparkling Red
-
-<cstim> Lets have some. ( goonie offers cstim a glass of fine Rutherglen sparkling red. )
- Transaction report: but it doesn't make much sense to show a total sum for that anyway, does it_
- s/_/?/ oh well, it might.
-
-<goonie> Option 1) display a total for each currency in the report.
-
-<cstim> exactly.
- Option 2) shows the total for only one currency, the report-currency.
- Option 3) somehow gets the right exchange rate so that it also ends up with only one total.
- I'd recommend option 2 for now. For option one you basically would have to copy the
-code out of the html-build-acct-table function cited above.
-
-<goonie> So, what happens to transactions not in the report-currency in option 2) - they aren't totalled?
-
-<cstim> Maybe with the tons of comments it is do-able
- goonie: yes, they dissolve in heat and aren't totalled.
-
-<goonie> OK, I think I can implement 1) and 2). 3 (which might have to be split into 3a, 3b . . . )
-can probably wait. Well, I could implement a "quickie" 3a that just grabs a current exchange
-rate and does the conversion on it.
-
-<cstim> again, for 1) you "just" have to copy ~100 lines of code from html-utilities.scm and
-adapt them to your table structure.
-
-<goonie> that has all sorts of problems, but might be useful if taken with a grain of salt.
- OK.
-
-<cstim> oh, a quick 3) costs you about 5 lines of extra cost.
-
-<goonie> I think I can cope with that :)
-
-<cstim> just look into pnl.scm and see how they (i.e. I) use gnc:make-exchange-alist and
-\a gnc:make-exchange-function both from \a src/scm/commodity-utilities.scm
-
-<goonie> OK, cool. Thanks for your help.
-
-<cstim> what did you mean by "quickie" 3a that just grabs a current exchange rate "
- a dialog box? a parameter? gnc-prices?
-
-<goonie> gnc-prices. or a parameter.
- something other than digging through a bunch of historical data trying to figure out what
-the exchange rate was at the time of particular transactions.
-
-<cstim> parameter: Bad. gnc-prices: Goood. I'd be happy if someone could implement that
-to augment the current code in commodity-utilities.scm Oh, the exchange rate at the time
-of a particular *transaction* is easy -- that's just the fraction value/damount .
-
-<goonie> not always - what if the transaction is (say) yen/yen but you want to display in dollars?
- for instance, our glass of saki, paid for in cash yen.
-
-<cstim> Yes, right. currently the commodity-utilities stuff uses a weighted average over the
-history. But using the last known exchange rate instead may be useful at times. Maybe I'll
-implmement something like that maybe if i have time :)
-
-<goonie>diff -up 'gnucash/src/engine/ Query.c' 'gnucash_transaction_report/src/engine/ Query.c'
-
-*/
diff --git a/libgnucash/doc/prices.txt b/libgnucash/doc/prices.txt
deleted file mode 100644
index a5d95bcf83..0000000000
--- a/libgnucash/doc/prices.txt
+++ /dev/null
@@ -1,37 +0,0 @@
-/** \page pricedocs Price Overview
-
-The Prices and the Price DB overview is in src/doc/design/engine.texinfo
-
-API: \ref Price
-
-Below, a few meta-notes about how prices and the GUI (should) interact:
-
-\section pricecompute Computing Prices
-
-When a price is computed from the (value/amt) that a user entered
-in a register, and this price is stored in the priceDB, then
-both the register entry and the price must have links to each other
-(via the KVP trees) so that each can be found from the other.
-
-This is needed because if the user enters an incorrect amt or value
-or date in the transaction register, and then corrects it later,
-possibly weeks or months later, the corresponding price in the
-priceDB must be fixed as well.
-
-Similarly, if a user deletes a transaction (possibly because it
-contains an error in date/amt/value), then it is advisable that
-the corresponding priceDB entry must be deleted as well (since
-it is not safe to assume that the price is 'correct').
-
-\section Rounding errors
-
-When doing price math in the register, one must be careful, because
-round-off errors can make 'obvious' math inaccurate. Note that if
-we define price as (value/amt), then we will find that
-value != price * amt due to roundoff handling. One must be careful
-and consistent in handling this in the register, as otherwise
-users will be driven crazy by inconsistent behaviour.
-
-(Linas Vepstas April 2003)
-
-*/
diff --git a/libgnucash/doc/qif.txt b/libgnucash/doc/qif.txt
deleted file mode 100644
index 685c75d2e9..0000000000
--- a/libgnucash/doc/qif.txt
+++ /dev/null
@@ -1,198 +0,0 @@
-/** \page qif QIF importer infrastructure.
-
- Derek Atkins <derek at ihtfp.com>
- 2004-01-07
-
- A work in progress....
-
-API: \ref Import_Export
-
-\section qifintro 0. Introduction
-
-The existing qif importer in src/import-export/qif-import is both hard
-to maintain and hard to re-integrate into the shared import
-architecture. Similarly, the half-completed re-write in qif-io-core
-is similarly hard to maintain (although it is arguably easier to
-integrate). One problem with both of these solutions is that they are
-written in Scheme, a language that many gnucash developers just don't
-understand well. Another issue is that the code is not commented and
-no documentation exists to help future developers track down bugs or
-extend the importer as QIF changes over time (c.f. Memorized
-Transaction import).
-
-As much as "complete rewrite" tends to be a lot of work for little
-gain, when few (if any) developers can understand the implementation
-well enough to make changes, a complete re-write may make sense. This
-document is an attempt to describe the architecture of the new
-importer, implemented in C, and how it interfaces to the rest of the
-import infrastructure.
-
-
-\section qifarch 1. Importer Architecture
-
-The importer is a multi-step, staged system that should implement a
-read, parse, convert, combine, filter, finish process. The importer
-starts with a clean import context and then each processing step
-modifies it as per the user's requirements. A small set of APIs allow
-the user to progress along the processing steps (and an internal state
-machine makes sure the caller proceeds in the proper order).
-
-The importer is driven by the UI code; the importer itself is just a
-multi-stage worker. The UI code calls each step in the process. For
-long-running operations the UI can provide a callback mechanism for a
-progress bar of completion.
-
-Each stage of the import process may require some user input. What
-input is required depends on the stage of the process and what the
-last stage returned. In some cases stages can be skipped. For
-example, during the conversion phase if the date format is unambiguous
-then no user input would be required and the "ask for date format
-disamiguation" input can be skipped.
-
-QUESTION: How does the importer relate the processing state back to
-the UI? Simiarly, how does it pass back specific disambiguating
-questions to ask the user (and how are those responses returned to the
-importer)?
-
-\section qifprocess 2. The Import Process
-
-The import process starts when the UI creates a new import context.
-All of a single import is performed within that context. The context
-model allows multiple import processes to take place simultaneously.
-
-The first step in the import process is selecting the file (or files)
-to be imported. The UI passes each filename to the importer which
-reads the file and performs a quick parse process to break the file
-down into its component QIF parts. While the importer should allow
-the user to iteratively add more and more files to the import context,
-it should also allow the user to select multiple files at once
-(e.g. *.qif) to reduce the user workload.
-
-Each imported file may be a complete QIF file or it may be a single
-QIF account file. In the latter case the UI needs to ask the user for
-the actual QIF account name for the file. Similarly, each file may
-need user intervention to disambiguate various data, like the date or
-number formats.
-
-QUESTION: If the user provides multiple files at once and each file
-has internal ambiguities (e.g. the date format), should the user be
-asked for each file, or can we assume that all the files have the same
-format? Perhaps the UI should allow the user to "make this choice for
-all files"?
-
-Once the user chooses all their files (they can also remove files
-during the process) the importer will combine the files into a common
-import, trying to match QIF accounts and transactions from different
-files. Part of this is duplicate detection, because QIF only includes
-half a transaction (for any QIF transaction you only know the local
-account, not necessarily the "far" account). If the importer sees
-multiple parts of the same transaction it can (and should) combine
-them into a single transaction, thereby pinning down the near and far
-accounts.
-
-The next series of steps maps QIF data objects to GnuCash data
-objects. In particular, the importer needs the help of the UI to map
-unknown QIF Accounts and Categories to GnuCash Accounts (the latter to
-Income and Expense Accounts) and QIF Securities to GnuCash
-Commodities. Finally the importer can use the generic transaction
-matcher to map the existing transactions to potential duplicates and
-also Payee/Memo fields to "destination accounts".
-
-At the end of this process the accounts, commodities, and transactions
-are merged into the existing account tree, and the import context is
-freed.
-
-
-\section qifobject 3. Importer Data Objects
-\verbatim
-QifContext
-QifError
-QifFile
-QifObject
- +-QifAccount
- +-QifCategory
- +-QifClass
- +-QifSecurity
- +-QifTxn
- +-QifInvstTxn
-\endverbatim
-
-\subsection qifinternal Internal Data Types
-
-QifHandler
-QifData
-
-\section qifapi 4. Importer API
-
-\subsection qifcontexts QIF Contexts
-\verbatim
-/** Create and destroy an import context */
-QifContext qif_context_create(void)
-void qif_context_destroy(QifContext ctx)
-
-/** return the list of QifFiles in the context. */
-GList *qif_context_get_files(QifContext ctx)
-
-/** merge all the files in the context up into the context, finding
- * matched accounts and transactions, so everything is working off the
- * same set of objects within the context.
- */
-void qif_context_merge_files(QifContext ctx);
-\endverbatim
-
-\section qiffiles QIF Files
-\verbatim
-/**
- * Open, read, and minimally parse the QIF file, filename.
- * If progress is non-NULL, will call progress with pg_arg and a value from
- * 0.0 to 1.0 that indicates the percentage of the file read and parsed.
- * Returns the new QifFile or NULL if there was some failure during the process.
- */
-QifFile qif_file_new(QifContext ctx, const char* filename,
- void(*progress)(gpointer, double), gpointer pg_arg)
-
-/** removes file from the list of active files in the import context. */
-void qif_file_remove(QifContext ctx, QifFile file)
-
-/** Return the filename of the QIF file */
-const char * qif_file_filename(QifFile file);
-
-/** Does a file need a default QIF account? */
-gboolean qif_file_needs_account(QifFile file);
-
-/** Provide a default QIF Account-name for the QIF File */
-void qif_file_set_default_account(QifFile file, const char *acct_name);
-
-/** Parse the qif file values; may require some callbacks to let the
- * user choose from ambiguous data formats
- * XXX: Is there a better way to callback from here?
- * Do we need progress-bar info here?
- */
-QifError qif_file_parse(QifFile ctx, gpointer ui_arg)
-\endverbatim
-
-\section qifstate 5. Importer State Machine
-
-The state machine has the following structure. Named states (and substates)
-must proceed in order. Some states (e.g. state b) have multiple choices.
-For example you could enter substates b1-b2, or you can run qif_file_remove.
-
-a. Create the context
- - qif_context_create
-b. Add/Remove files to be imported
- b1. Add file
- - qif_file_new
- b2. Parse the added file
- - qif_file_parse
- Note that this needs to callback into the ui to handle ambiguities
- - qif_file_remove
- If the user wants to remove some files from the import context
- - repeat (b) as necessary until user choses to move to (c)
-c. Once all files are chosen, merge internally and continue the process
- - qif_context_merge_files
-d. map qif accounts to gnucash accounts
-e. map qif categories to gnucash accounts
-f. map qif securities to gnucash commodities
-g. duplicate detection with existing gnucash txns
-h. transaction matcher (map one-sided txns using Payee/Memo info)
-*/
diff --git a/libgnucash/doc/sx.rst b/libgnucash/doc/sx.rst
deleted file mode 100644
index ac9c0417bc..0000000000
--- a/libgnucash/doc/sx.rst
+++ /dev/null
@@ -1,426 +0,0 @@
--*- mode: rst; buffer-file-coding-system: utf-8 -*-
-
-Scheduled Transactions
-======================
-
-TODO
-----
-
-- meta
-
- - [ ] GncSxListTreeModelAdapter: s/real/adapted/
- - [ ] generic tree model adapter setup code
- - [ ] move documentation into doxygen comments, here and in sources.
- - [x] move files around
- - [x] printf -> logging
-
-- core
-
- - ! [ ] @fixme-s
- - ! [ ] after updating/merging new instances, ensure sx-instance-state consistency
- - [x] sx list -> qof collection
- - [x] sx engine events
-
- - [x] sx list collection add/remove -- sx-list GNC_EVENT_ITEM_ADDED, _REMOVED
- - [x] sx modified -- QOF_EVENT_MODIFY
-
- - [x] sx upcoming instance model
-
- - ! [x] implement sort model
-
- - [x] rename, re-home gnc-sx-instance-model:sxsl_get_sx_vars
- - [x] rename, re-home gnc-sx-instance-model:parse_vars_from_formula
-
-- unit testing
-
- - [ ] model updating in the face of change
-
- - [ ] insert sx
- - [ ] remove sx
- - [ ] update sx
-
- - [ ] add instances
- - [ ] remove instances
- - [ ] make "weird"
-
- - [ ] ± disabled flag
-
- - [x] ensure state consistency model is upheld
- - [ ] check variables-unbound logic
- - [ ] verify summary counts
- - [ ] check "since last run" states
-
- - [ ] specious datafile dirty-ing
- - [ ] -autocreate[, ±notify]
- - [ ] +autocreate, -notify
- - [ ] +autocreate, +notify
- - [ ] +autocreate, -notify, w/postponed
- - [ ] +autocreate, +notify, w/postponed
-
- - [ ] bugs
-
- - [?] Expired scheduled transactions never run - <https://bugs.gnucash.org/show_bug.cgi?id=375892>
-
- - remove
-
- - [x] display-using src/gnome-utils/test/test-sx.c
-
-- bugs
-
- - ! [x] with SLR open (with instances), add variables to SX; only newly-created instances will have appropriate variable tables.
-
- - ! [x] parse from 1.8 file doesn't setup start date correctly;
- daily-auto-yes-notify.xac has start date of 2006-09-26, but new TXN is
- for $today.
-
- - [x] this causes phantom "SX has been changed, confirm cancel?" problems.
-
- - [x] created/review txns disappear, eventual crash [ve20070303]_
-
- - ! [x] auto-create (+notify) txns not in review list. [ve20070209]_
-
- - [x] sx-from-trans: "unknown get.type [3]" [dh20070120]_
-
- - ! [x] crash with two sx lists open and SX mutation
-
- - I'm pretty sure this is due to SX lists not getting cleaned up on page close, somehow.
-
- - [x] no way to clear a variable entry [ve20070209]_
-
-.. [dh20070120] https://lists.gnucash.org/pipermail/gnucash-devel/2007-January/019667.html
-.. [ve20070209] https://lists.gnucash.org/pipermail/gnucash-devel/2007-February/019834.html
-.. [ve20070303] https://lists.gnucash.org/pipermail/gnucash-devel/2007-March/020069.html
-
-- sx list page
-
- - [/] make into split panel
-
- - [ ] fix default slider position
- - [ ] conf-save slider position
-
- - ! [x] use gnc-tree-view
- - ! [x] save/restore state
-
-- sx editor
-
- - [/] clean up source formatting
- - [ ] move "non-editor" general app/ui code out of bottom of dialog-sx-editor.c
- - [x] re-layout dialog
-
- - tabs: "overview", "frequency", "template transaction" [, "estimation"]
-
- - [ ] model-ize
-
- - (check_consistent, especially...)
-
-Notes::
-
- GncSxEditModel* gnc_sx_edit_model_new(SchedXaction *sx);
-
- gnc_sxed_check_changed( GncSxEditorDialog *sxed )
- gnc_sxed_check_consistent( GncSxEditorDialog *sxed )
- gnc_sxed_save_sx( GncSxEditorDialog *sxed )
-
- gchar* gnc_sx_edit_model_get_name(GncSxEditModel *mdl);
- void gnc_sx_edit_model_set_name(GncSxEditModel *mdl, gchar *new_name);
-
-- gnc_dense_cal
-
- - [ ] code cleanup
-
- - [x] min-size
-
- - [ ] change number-of-month properties to display-named properties (width, length)
- - [ ] gconf setting for dense-cal font-size reduction
- - [?] better transient/floating window
- - [/] (re-format file)
- - [x] eliminate the "couldn't find tag [1]" messages.
- - ! [x] font handling: gdk -> pango
- - [x] start-of-week := {sun,mon} (via locale)
- - [x] {0, 1, 2, 3, 4, 6, 12} month selection for dense calendar
-
- - [x] conf-save value
-
- - [x] set_model(GncTemporalInstancesModel *mdl)
-
- - [x] new interface creation.
- - [x] register callbacks for signals
-
- - [x] remove clist usage
-
-- sx-from-trans
-
- - [?] convert to GObject
- - [x] hookup destroy/finalize
-
-- FreqSpec
-
- - [#] type+ui-type -> type
-
-- use Recurrence instead of FreqSpec
-
- - ! [x] load druid
- - ! [x] sx-from-trans, <https://bugs.gnucash.org/show_bug.cgi?id=412633>
- - ! [x] XML migration, handling
-
- - xml:freqSpec -> obj:Recurrence
-
- - [x] none (Recurrence doesn't support)
- - [x] once
-
- - [x] if once, fix Recurrence date to be SX start date. :p
-
- - [x] daily
- - [x] daily [m-f] (composite)
- - [x] weekly, single
- - [x] weekly, multiple (composite)
- - [x] monthly (+quarterly, tri-anually, semi-annually, yearly)
- - [x] semi-monthly (composite)
-
- - [x] write Recurrences into new-version SX
-
- - gnc-frequency
-
- - ! [x] Support Recurrence
-
- - [x] in
- - [x] out
-
- - ! [x] Support 'last-day-of-month'
- - [x] simplify
-
- - [x] remove daily [m-f] (-> weekly)
- - [x] remove biweekly page (-> weekly)
- - [x] remove > monthly pages (-> monthly)
-
- - [x] clean up, reformat source
-
- - gnc-plugin-page-sx-list
-
- - [x] gnc_plugin_page_sx_list_cmd_new
-
- - dialog-sx-editor
-
- - [x] gnc_sxed_check_changed
- - [x] gnc_sxed_check_consistent
- - [x] gnc_sxed_update_cal
- - [x] gnc_sxed_save_sx
-
- - sx list
-
- - [x] recurrence_cmp(...)
- - [x] More compact recurrenceListToString(...).
-
- - [ ] remove FreqSpec code
-
- - [x] don't write FreqSpecs out.
-
- - [ ] SX code
-
- - [ ] engine
- - [ ] backend
- - [ ] gnc-frequency
- - [ ] gnc-dense-cal-store
-
- - [x] src/gnome/druid-acct-period.c
-
-- gnc_frequency
-
- - [ ] 'every x months' spin button makes large jumps::
-
- <andi5> jsled: another topic: you have probably seen the "every x months" spin button make jumps greater than one, right? ... this seems to be due to a spin button timeout event which controls "fast-forward" spinning... it is run because the changed(?) signal handler is too slow
-
- - [ ] support nth-weekday Recurrence period.
-
- - [x] Freq=none doesn't work::
-
- * 17:00:29 CRIT <gnc.engine.recurrence> recurrenceListNextInstance: assertion `rlist && ref && next && g_date_valid(ref)' failed
- * 17:00:36 CRIT <gnc.engine.sx> gnc_sx_set_schedule: assertion `sx && schedule' failed
-
-- since-last-run
-
- - [ ] "reminder" instances should show number of days until due
- - [ ] "Find unfinished" button; count; sensitize Ok as function of unfinished.
- - [ ] bold SX names [tw20070614]_
- - [ ] checkbox/option to show/hide reminders [tw20070614]_, or a multi-part tree [tw20070619]_
- - [ ] filter/remove SXes that don't have any instances in the list [tw20070614-2]_
- - [ ] remove tree expand controls, except for non-to-create instances with variables [tw200070614-2]_
- - [x] text changes [tw20070614]_
-
- - "Sx, Instance, Variable" -> "Transaction"
- - "Instance State" -> "Status"
- - "Variable Value" -> "Value"
-
- - ! [x] save/restore dialog window size
- - [x] remove split pane
- - [x] "auto" scrollbars
- - ! [x] rewrite adapter (re-)population logic
- - [x] move "effect_change" up to app-utils/, test.
- - [x] move state-change up to app-utils
- - [x] move variable-setting up to app-utils
- - [x] move summarization up to app-utils
- - [x] add reminders, postponed to SxInstanceModel
- - [x] add mutation support to sx instance model
-
- - [x] state machine
-
- - [x] add variable state to sx instance model
-
- - [x] handle (hidden/system not for editing) variables.
-
- - [x] add sx_upcoming_instance_model()
-
- - [x] add effect_auto_create()
-
- - [x] add some sort of "ready to go" flag and api
-
- - [x] variable setting, primarily
-
- - [x] some sort of commit_changes()
- - [x] add variable table to instances
- - [x] ui: add 'review created transactions' checkbox to SLR dialog
- using txn search.
-
-.. [tw20070614] https://lists.gnucash.org/pipermail/gnucash-devel/2007-June/020718.html
-.. [tw20070614-2] https://lists.gnucash.org/pipermail/gnucash-devel/2007-June/020729.html
-.. [tw20070619] https://lists.gnucash.org/pipermail/gnucash-devel/2007-June/020757.html
-
-- destroy/cleanup, notes:
-
- - dispose: break references; callable multiple times
- - finalize: complete destruction; just before free; only called once
-
-Pedantic Todo
--------------
-
-- s/SchedXaction/Scheduled/
-- s/temporal_state/instance_sequence_context/
-- change instance variable from 'i' to '__i' or something
-
-============================================================
-
-(eventually real documentation... (?))
-
-Since Last Run
---------------
-
-+------------------+------------------+------------------+
-| Thing | State | Value |
-+------------------+------------------+------------------+
-| - Foo | | |
-+------------------+------------------+------------------+
-| - 2006-08-27 | [Postponed|v] | |
-+------------------+------------------+------------------+
-| - variable-a | | 42 |
-+------------------+------------------+------------------+
-| - variable-b | | 75 |
-+------------------+------------------+------------------+
-| - 2006-08-27 | [To-Create|v] | |
-+------------------+------------------+------------------+
-| - variable-a | | 31 |
-+------------------+------------------+------------------+
-| - variable-b | | (value needed) |
-+------------------+------------------+------------------+
-
-
-The since-last-run dialog is a key user interface. More frequently than the
-SX list or editor, the user will be in the process of creating transaction
-instances through this interface.
-
-The old SLR dialog has the following stages:
-
-- Reminders
-
- - can be promoted to "to-create"
-
-- Auto-created, with notification
-- To-Create
-
- - postponed, to-create
- - ignore state.
-
-- Created review
-- Obsolete SX cleanup
-
-The new SLR dialog will have the following:
-
-- Creation (treemodel consisting of)
-
- - auto-created
- - reminder
- - postponed
- - to-create
- - [obsolete SX]?
-
-There is no separate to-review page, however the user may (optionally) want
-to see the created transactions. This is done using the transaction-search
-functionality over the created transactions by ID.
-
-Upcoming instance states
-------------------------
-
-- reminder -> to-create
-- postponed -> to-create
-- to-create -> postponed
-- to-create -> ignore
-- to-create -> created [terminal]
-
-Definitions:
-
-reminder
- a transient upcoming transaction that will not be created.
-postponed
- a historical to-create transaction that the user has explicitly deferred.
-to-create
- an upcoming SX instance that should be created.
-ignore
- a scheduled instance the user has explicitly prevented the instantiation of.
-created
- the instance has been created in this interaction cycle.
-
-Formula Parsing
----------------
-
-A SXes formula is parsed in the context of:
-
-- the template transaction
-
- - the accounts of the splits
-
-- the sequence number
-- the date of the transaction
-- a variable-binding table.
-
-Testing Notes
--------------
-
-- auto-create
-
- - auto-create with postponed instances shouldn't destroy postponed
- instances
-
-- basic sequence stuff
-
-dialog-sxsincelast.c: ~L1241:
-"Handle an interesting corner case of postponing or
-ignoring the first instance. We only want to increment the
-counters for newly-discovered-as-to-be-created SXes."
-
-- auto-create
-
- - auto-create transactions can be created w/o user interaction
-
- - their state is transitioned to 'created', which is not modifiable
-
- - auto-create (+notify) transactions should be displayed, even if they are
- the only transactions created.
-
- - auto-create (-notify) transactions should not be displayed, unless there
- are other transactions.
-
- - Scenarios
-
- - only auto-create (-notify): no SLR, info dialog w/count (***)
- - only auto-create (+notify): SLR dialog, already created
- - others, auto-create (-notify): SLR dialog, incl. created
- - others, auto-create (+notify): SLR dialog, incl. created
diff --git a/libgnucash/doc/tax.txt b/libgnucash/doc/tax.txt
deleted file mode 100644
index 78fb179299..0000000000
--- a/libgnucash/doc/tax.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-/** \page taxnotes Some notes about taxes
-
-From: Jon Kaare Hellan <Jon.K.Hellan at item.ntnu.no>
-
-Norwegian rules are more or less as follows:
-
-You pay income tax on
-(sale price - commission) - (adjusted purchase price + commission)
-
-Adjusted purchase price?? That's what makes us different.
-
-Each Jan. 1., the cost base of stocks you hold is adjusted by some
-amount. How it is computed does not matter here, but the idea is that
-once the company has paid tax on a profit, a corresponding amount of
-capital gains becomes tax free to the stockholders. Theoretically
-attractive, difficult in practice.
-
-So I need a way to keep track of these adjustments register for each
-stock in a portfolio.
-
-*/
diff --git a/libgnucash/doc/user-prefs-howto.txt b/libgnucash/doc/user-prefs-howto.txt
deleted file mode 100644
index ccbd3eae47..0000000000
--- a/libgnucash/doc/user-prefs-howto.txt
+++ /dev/null
@@ -1,63 +0,0 @@
-/** \page userprefs User Preferences HOWTO
-
-Well, since I just explained this issue to Benoit on IRC, I thought I could
-just post it here. If somebody (Benoit?) considers it helpful, you might add
-it somewhere to CVS.
-
-\section userprefsadd How to add a preferences option
-
-This text explains how to add options to the global preference dialog
-from a module. The text uses the example of one simple boolean option
-in the import-export/hbci module ("Cache password in memory?").
-
-The option is created in the file src/import-export/hbci/hbci.scm,
-with the following function call as a top-level function in that file:
-
-\verbatim
-(gnc:register-configuration-option
- (gnc:make-simple-boolean-option
- (N_ "Online Banking & Importing") (N_ "HBCI Remember PIN in memory")
- "b" (N_ "Remember the PIN for HBCI in memory during a session")
- #f))
-\endverbatim
-
-The actual option is created by the function call to
-gnc:make-simple-boolean-option. Its first (string) argument is the
-tab (page) name. If the option is supposed to appear on an existing
-tab (page), the string has to match *exactly* the string used in
-src/app-utils/prefs.scm. The second (string) argument above is the
-actual option name. For lookup, this *exact* string will need to be
-used again.
-
-For other (more complex) types of options, look up the
-gnc:make-xyz-option function to create your favorite option type in
-src/app-utils/options.scm. Also, if one or more options are supposed
-to go on a *new* tab/page, simply specify a tab/page name that didn't
-exist yet. It will automatically be added.
-
-During the actual program run, the option is looked up only once, in
-src/import-export/hbci/hbci-interaction.c line 53:
-
-\verbatim
-cache_pin =
- gnc_lookup_boolean_option(N_("Online Banking & Importing"),
- "HBCI Remember PIN in memory",
- FALSE);
-\endverbatim
-
-The third argument here is the default value in case the lookup
-fails. The C function prototypes for lookup of other options can be found in
-src/app-utils/global-options.h. A lookup of a global preference in
-Scheme can be seen e.g. in src/report/reports/standard/register.scm
-line 556:
-
-\verbatim
- (gnc:option-value (gnc:lookup-global-option "User Info" "User Name"))
-\endverbatim
-
-I.e., the option itself has to be looked up first by
-gnc:lookup-global-option (from src/app-utils/prefs.scm), and then the
-function gnc:option-value returns the actual value of the option
-(defined in src/app-utils/options.scm).
-
-*/
diff --git a/libgnucash/engine/CMakeLists.txt b/libgnucash/engine/CMakeLists.txt
index 3a5c3e4c4a..84b39bb436 100644
--- a/libgnucash/engine/CMakeLists.txt
+++ b/libgnucash/engine/CMakeLists.txt
@@ -276,8 +276,6 @@ install(TARGETS gnc-engine
install(FILES ${engine_HEADERS} DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/gnucash)
set(engine_EXTRA_DIST
- design.txt
- extensions.txt
iso-4217-currencies.xml
iso-currencies-to-c.xsl
kvp_doc.txt
diff --git a/libgnucash/engine/Split.h b/libgnucash/engine/Split.h
index f33b63b5b5..0877edcb00 100644
--- a/libgnucash/engine/Split.h
+++ b/libgnucash/engine/Split.h
@@ -62,6 +62,8 @@ GType gnc_split_get_type(void);
/** @name Split Reconciled field values
+ These define the various reconciliations states a split can be in.
+
If you change these
be sure to change gnc-ui-util.c:gnc_get_reconciled_str() and
associated functions
diff --git a/libgnucash/engine/design.txt b/libgnucash/engine/design.txt
deleted file mode 100644
index 1dca347f6c..0000000000
--- a/libgnucash/engine/design.txt
+++ /dev/null
@@ -1,431 +0,0 @@
-/** \page backendold Engine Architecture (old)
-
-API: Backend
-
-\section oldintro Introduction
-
-This document is becoming obsolete. Please refer to the design
-documentation in src/doc/design for a complete description of the
-Engine architecture.
-
-The only remaining architecture flaw is related to the GnuCash XML v2
-backend modularisation. QofSession includes a dynamic method of loading
-a QofBackend that supersedes the use of gnc_module_load that currently
-loads the module using guile/scheme. When the old XML backend is replaced
-by Sqlite, this will be resolved.
-
-Note that this flaw <b>does not appear in QOF</b> itself. The C code
-enabling the entire guile/scheme load mechanism is GnuCash only.
-
-\subsection oldflaw Architecture Flaw
-
-What does Architecture Flaw really mean? There is a Soviet joke from the 1960's:
-
-A westerner in Moscow stops a man to ask him the time. The man puts
-down his breifcase, and flicks his wrist to look at his watch. "The
-time is 7:03, the temperature is 12 degrees C, the air presssure is
-950 mmHg and falling." The westerner remarks with considerable
-interest, "Why, that's a mighty fine watch you have there! We don't
-have anything like that in the America!" The Soviet responds, "Why
-yes, this demonstrates the superiority of Soviet engineering over
-decadent captalist design." Stooping to pick up his briefcase,
-he mumbles half to himself, "If only these batteries weren't so heavy."
-
-There is only one place where the engine requires the use of guile.
-This is the remaining architecture flaw, see above.
-
-\section oldreview Accounting Engine
-
-This document reviews the operation of, and various design points
-pertinent to the GnuCash accounting engine. The latest version
-of this document can be found in the engine source-code directory.
-
-\section enginestock Stocks, non-Currency-Denominated Assets
-
-The engine includes support for non-currency-denominated assets,
-such as stocks, bonds, mutual funds, inventory. This is done with
-two values in the Split structure:
-
- double share_price;
- double damount;
-
-"damount" is the number of shares/items. It is an "immutable" quantity,
-in that it cannot change except by transfer (sale/purchase). It is the
-quantity that is used when computing balances.
-
-"share_price" is the price of the item in question. The share-price is
-of course subject to fluctuation.
-
-The net-value of a split is the product of "damount" and "share_price".
-The currency balance of an account is the sum of all "damounts" times
-the latest, newest share-price.
-
-Currency accounts should use a share price of 1.0 for all splits.
-
-To maintain the double-entry consistency, one must have the following
-hold true:
-
- 0.0 == sum of all split values.
-
-If all splits are in the same currency, then this becomes:
-
- 0.0 == sum of all ((split->damount) * (split->share_price))
-
-Thus, for example, the purchase of shares can be represented as:
-
- source:\n
- debit ABC Bank for $1045 (1045 dollars * dollar "price" of 1.00)
-
- destination:\n
- credit PQR Stock for $1000 (100 shares at $10 per share)
- credit StockBroker category $45 in fees
-
-If the splits are in mixed currencies and securities, then there must
-be at least one common currency/security between all of them. Thus,
-for example:
-
- source:\n
- debit ABC Bank for $1045 (1045 dollars * dollar "price" of 1.00)
-
- destination:\n
- credit VolkTrader for 2000 DM (1000 dollars at 2.0 mark per dollar)
- credit Fees category $45 in fees
-
-If the "currency" field is set to "DM" for the VolksTrader account,
-and the "security" field is set to "USD", while the currency for ABC bank is
-"USD", then the balancing equation becomes:
-
-0.0 = 1045 * $1.00 - $1000 - 45 * $1.00
-
-Note that we ignored the price when adding the second split.
-
-\subsection enginestock Recoding a Stock Price
-
-A stock price may be recorded in a brokerage account with a single
-split that has zero value:
-(share price) * (zero shares) == (zero dollars)
-This transaction does not violate the rules that all transactions must
-have zero value. This transaction is ideal for recording prices. Its
-the only transaction type that may have a single split; everything else
-requires at least two splits to balance. (at least when double-entry
-is enabled).
-
-\subsection engineplit Recording a Stock Split
-
-Stock splits (i.e. when a company issues x shares of new stock for every
-share already owned) may be recorded with a pair of journal entries as
-follows:
-
-(-old num shrs) * (old price) + (new num shrs) * (new price) == 0.0
-
-where each journal entry credits/debits the same account.
-Of course (new num shrs) == (1+x) * (old num shrs)
-and the price goes inversely.
-
-\section enginestock Stock Options
-
-Stock options are not currently supported. To support them, the
-following needs to be added:
-
-A stock option is an option to purchase stock at a specified price.
-Options have an expiration date. When you purchase an option it is
-pretty much like buying stock. However, some extra information needs
-to be recorded. To fully record an option purchase, you need to record
-the underlying stock that the option is on, the strike price (i.e. the
-price that the underlying stock can be purchases for), an expiration date,
-and whether the option is a put or a call. A put option is the option
-to sell stock at the strike price, and a call option is the option to
-purchase stock at the strike price. Once an option is bought, it can
-have one of three dispositions: it can be sold, in which case, it is
-pretty much just like a stock transaction. It can expire, in which
-case the option is worthless, and (IIRC) can be/is treated as a sale
-at a zero price. Thirdly, it can be exercised, which is a single
-transaction whereby stock is purchased at the strike price, and
-the option becomes worthless.
-
-Another point: with standardized options one option contract represents
-the ability to purchase (with a call option) or sell (with a put option)
-100 shares of the underlying stock.
-
-\seection engineerror Error Reporting
-
-The error reporting architecture (partially implemented), uses a globally
-visible subroutine to return an error. In the naivest possible implementation,
-the error reporting mechanism would look like this:
-\verbatim
- int error_num; // global error number
-
- int xaccGetError (void) { return error_num; }
-
- void xaccSomeFunction (Args *various_args) {
- if (bad_thing_happened) error_num = 42;
- }
-\endverbatim
-Many programmers are used to a different interface, e.g.
-\verbatim
- int xaccSomeFunction (Args *various_args) {
- if (bad_thing_happened) return (42);
- }
-\endverbatim
-Because of this, it is important to explain why the former design was
-chosen over the latter. Let us begin by listing how the chosen design
-is as good as, and in many ways can be better to the later design.
-
--# Allows programmer to check for errors asynchronously, e.g. outside
- of a performance critical loop, or far away, after the return of
- several subroutines.
--# (with the right implementation) Allows reporting of multiple, complex
- errors. For example, it can be used to implement a trace mechanism.
--# (with the right implementation) Can be thread safe.
--# Allows errors that occurred deep in the implementation to be reported
- up to much higher levels without requiring baggage in the middle.
-
-The right implementation for (2) is to implement not a single
-variable, but a stack or a ring (circular queue) on which error codes
-are placed, and from which error codes can be retrieved. The right
-implementation for (3) is the use pthread_getspecific() to define a
-per-thread global and/or ring/queue.
-
-\section engineisolation Engine Isolation
-
-Goals of engine isolation:
-- Hide the engine behind an API so that multiple, pluggable engines
- could be created, e.g. SQL or CORBA.
-- Engine users are blocked from being able to put engine internal
- structures in an inconsistent state. Updates are "atomic".
-
-Some half-finished thoughts about the engine API:
-
-- The engine structures should not be accessible to any code outside
- of the engine. Thus, the engine structures have been moved to
- AccountP.h, TransactionP.h, etc.
- The *P.h files should not be included by code outside of the engine.
-- The down-side of hiding is that it can hurt performance. Even trivial data
- accesses require a subroutine call. Maybe a smarter idea would be to leave
- the structures exposed, allow direct manipulation, and then "copy-in" and
- "copy-out" the structures into parallel structures when a hidden back end
- needs to be invoked.
-- the upside of hiding behind an API is that the engine can be
- instrumented with extension language (perl, scheme, tcl, python) hooks
- for pre/post processing of the data. To further enable such hooks, we
- should probably surround all operations on structures with "begin-edit"
- and "end-edit" calls.
-- begin/end braces could potentially be useful for two-phase commit schemes.
- where "end-edit" is replaced by "commit-edit" or "reject-edit".
-
-\section enginereconcile Reconciliation
-
-The 'reconcile' state of a transaction can have one of the following values:
-
-\verbatim
-// Values for the reconciled field in Transaction:
-#define NREC 'n' // not reconciled or cleared
-#define CREC 'c' // The transaction has been cleared
-#define YREC 'y' // The transaction has been reconciled
-#define FREC 'f' // frozen into accounting period
-\endverbatim
-
-(Note that FREC is not yet used/implemented ...)
-
-The process of reconciliation works as follows:
--# User enters new transaction. All splits are marked 'n' for 'new'
- or 'no, not yet reconciled'.
--# User believes that the transaction has cleared the bank,
- e.g. that a cheque written out has been deposited/cashed.
- User clicks in the 'R' column in the register gui,
- marking the split 'c' for 'cleared'. User can freely
- toggle this flag from the GUI with essentially no penalty,
- no complaints. This is a 'safe' operation. Note that the
- register shows the 'cleared' subtotal, which is, essentially,
- a guess of the banks view of the account balance.
--# When user gets the bank statement, user launches the
- reconcile dialogue. This dialogue is used to match transactions
- on the bank statement with which is recorded locally.
- Reconciled transactions are marked with a 'y'.
- Note that once a transaction has been marked 'y', and the
- user has 'finished' with the reconcile dialogue, then it
- should be 'hard' to change the reconcile state from
- the ordinary register dialogue. It should be sort-of
- 'set in stone'. (The engine does NOT enforce this,
- only the gui enforces this.)
--# When the books are closed, all splits should be marked
- 'frozen', and become truly un-editable. The engine should
- enforce 'frozen', and just plain not allow editing of closed
- books, period. The only wat to change this would have been
- to re-open the book. (and the reopening of a book would
- change all 'f' to 'y'.)
-
-About storing dates associated with reconcile:
-\verbatim
-> I think that there should be a date stamp attached to the reconciliation
-> field so that as well as knowing that it has been reconciled, you also
-> know *when* it was reconciled.
->
-> This isn't so important for personal finances for the periodic user; I
-> have in the past wanted to know when a particular transaction was
-> reconciled. This is useful if you want to trace back from the
-> electronic record to determine when the item actually cleared through
-> the bank.
->
-> This means that I can look at Cheque #428, written Jan 1/97, cashed in May
-> 1997 (it sat in someone's desk for a while) in the computer system and say
-> "Ah. It was marked as reconciled on June 12th/97. That was when I did the
-> reconciliation of the May bank statements. Ergo, the cheque cleared in May,
-> and that's the statement to go to to find a copy of the cheque..."
->
-> It's not terribly important for cheques that get cashed right away; it *is*
-> for things that hang around uncashed for a while.
-\endverbatim
-
-If the above is implemented, what date should be stored if the user
-toggles the recn flag a few time? The date of the last toggle?
-The very first date that it was recn'ed?
-
-\section enginebackup Automatic Backup
-
-The following has been implemented:
-
-Have (by default) xacc create a backup file
-filename-timestamp.xac on every save. This will eat up some disk
-space until you go back and kill the older versions, but it's
-better than not realizing that the data's subtly corrupt a week
-later.
-
-A lot of small-office/home systems do this. primarily useful as a
-historical record, in case you accidentally wipe out something, and
-don't spot it until later. Limited usefulness, but very nice in case
-you accidentally delete an entire account.
-
-To a limited degree, it provides atomicity/consistency/etc at the
-course-grained account-group level.
-
-\section enginetransaction Transaction Processing
-
-There is a rudimentary level of "TP" build in, via the routines
-xaccTransBeginEdit(), xaccTransRollbackEdit(), and xaccTransCommitEdit(),
-which allow changes to be made to a transaction, and then committed,
-or rejected at the end. Handy for the GUI, if the user makes a bunch
-of changes which they don't want to keep; also handy for an SQL back end,
-where the Commit() routine triggers the actual update of the SQL database.
-
-Note: 'Commit' is sometimes called 'post' in other systems: The
-act of 'committing' a transaction is the same as 'posting' the
-transaction to the general journal.
-
-Some important implementation details to understand: the GUI currently
-uses begin/end as a convenience, and thus, may hold a transaction in
-the 'edit' state for a portentially long time (minutes or hours).
-Thus, begin/end should not map naively to a table-lock/unlock.
-Instead, an optimistic-locking scheme, as below, is preferred.
-
-The SQL back-end should implement posting entirely in the
-'Commit()' routine. The pseudo-algorithms should look as follows:
-
-\verbatim
- BeginEdit () {
- // save a copy of what it was before we start editing
- old_transaction = this;
- }
-
- SetValue (float amount) {
- // some example editing done here
- this->value = amount;
- }
-
- Commit () {
- LockTable();
- current = QueryTransaction();
- // check ton make sure that what the sql db stores
- // is identical to what we have on record as the
- // 'original' transaction. If its not, then someone
- // got in there and modified it while we weren't
- // looking; so we better report this back to user.
- if (current != old_transaction) Error(); Unlock(); return err;
-
- // otherwise, all is OK, we have successfully obtained
- // the lock and validated the data, so now just update things.
- StoreTransaction (new_transaction);
- UnlockTable();
- old_transaction = NULL;
- }
-
- Rollback () {
- // throw away the edits
- this = old_transaction;
- old_transaction = NULL;
- }
-\endverbatim
-
-The GUI should check to make sure that the Commit() routine didn't fail.
-If it did fail, then the GUI should pop up a notice to the user stating
-that the fundamental underlying data has changed, and that the user
-should try doing the edit again. (It might be nice to indicate which
-other human user might have changed the data so that they could
-coordinate as needed.)
-
-\section enginelogs Journal Logs
-
-The following has been implemented; see TransLog.c for details.
-
-Transaction logs. The idea was that every time a transaction
-was called that would cause a data update, the information that
-was updated would be dumped out into an "append only" log file.
-
-This somewhat parallels what better database systems do to ensure
-integrity; Oracle, for instance, has what is called an "archive log."
-You have a copy of the database "synced up" as at some point in time,
-and can apply "archive logs" to bring that old copy of the database
-up to date should something go wrong to trash today's copy.
-
-In effect, you'd have things like
-
-\verbatim
-=== 97/01/01 04:32:00 === Add Transaction ==== [whatever was added] ====
-=== 97/01/01 04:32:02 === Delete Transaction ==== [whatever was deleted] ====
-\endverbatim
-
-It also is a useful debugging tool, as if you make sure that the
-"log_transaction()" call starts by opening the log file, writes, and
-then closes and syncs, you know what is going on with the data even if
-horrible things happen to the "master" database file.
-
-\section enginemanagement Session Management
-
-To allow the user of the engine some guarantee of atomic updates,
-serialized file I/O, related miscellany, the concept of a session
-is supported. No file IO can be performed until a session has
-been created, and file updates are not guaranteed atomic unless
-performed within a SessionBegin/SessionEnd pair.
-
-Note that (in the current implementation) data can be manipulated
-outside of the session; its just that it cannot be saved/made persistent.
-
-The goal of session management is to ensure that e.g. two users don't end
-up editing the same file at the same time, or, e.g. that an automatic
-stock-quote update daemon running under a different pid doesn't trash
-data being currently edited by the user.
-
-\section enginetodo Remaining Work Items
-
-To find other remaining work items in the code, grep for the string
-"hack alert".
-
-See also the \ref todo.
-
-\section engineenhance Ideas for engine enhancements:
-
--# Have (by default) gnucash immediately re-read a file after every
- write, and compare the two resulting AccountGroups for equality.\n
- During development, this is a good idea, as it will help uncover
- thinko's more quickly, instead of letting them hide for weeks or months
- (as the last one did). Its not a bad self-consistency check when
- monkeying with the internals, damn the performance.\n
- It can be removed/disabled for product versions.
-
-\section olddate Needs updating.
-
-This document is dated May 2000
-
-Updated the architecture flaw section, June 2005.
-
-*/
diff --git a/libgnucash/engine/extensions.txt b/libgnucash/engine/extensions.txt
deleted file mode 100644
index 52dfcd1bce..0000000000
--- a/libgnucash/engine/extensions.txt
+++ /dev/null
@@ -1,70 +0,0 @@
-/** \page gnucashextension Proposed GnuCash Extensions
-
-The following are proposals for various, as-yet-unimplemented
-enhancements. The goal of this document is to understand some
-of the changes that will come soon to the interfaces.
-
-\section accountperiods Accounting Periods
-
-Accounting periods are implemented by creating an object that
-describes the accounting period, and then assigning every
-transaction to at least one period.
-
-\verbatim
-typedef struct _accountingPeriod {
- GUID guid; // id
- char *name; // user-selectable name
- int kind; // enum {none, week, month, quarter, year }
- Timespec * start_date; //
- Timespec * end_date;
- AccountGroup *topgrp; // chart of accounts for this period.
-} AccountingPeriod;
-\endverbatim
-
-The Transaction struct has to be extended with a period guid.
-Every transaction can belong to at most one accounting period.
-
-In addition, each chart of accounts needs to be extended with
-an accounting period as well. This allows 'old' accounts to be deleted
-from 'open books', without having to delete that same account from old
-closed books. Basically, a new chart of accounts needs to be written
-out/read from the engine for each new accounting period.
-
-The xaccPeriodClose() subroutine performs the following:
-- crawl over all transactions and mark them as being part of this
- accounting period (actually, new transactions should by default be
- getting put into the currently open period...)
-- find the equity account (what if there is more than one equity account
- ?? what if equity has sub-accounts ?? )
-- transfer all income/expense to equity (shouldn't the equity account
- match the income/expense hierarchy?)
-- return a new account group with new opening balances ...
-
-\section transactionchanges Changes to Transaction Structure
-
-Add an accounting period guid (see above).
-
-\section splitchanges Changes to Journal Entry (Split) Structure
-
-\subsection splitvoucher Voucher Reference
-
-Add a char * voucher; This is a generic id string that somehow
-identifies the piece of paper/electronic document(s) that indicate
-where/how to find the paper trial for this entry. This list of id's
-should probably be a list of key-value pairs, where the keys & values
-can be completely configured by the user, and hold the needed data
-that the user wants to store. For the SQL backend, this is a key
-to a user-definable table.
-
-\section bankingchanges Additional Banking Info
-
-BankId -- routing & transit number (US) or Bankleitzan (DE) or Banque (FR)
-BranchID -- Agence (FR), blank for other countries
-
-AcctKey -- Cle (FR), blank in others
-
-Account type enumerants:
-bank account types:
- checking, savings, moneymarket, creditline, cma (cash amangement account)
-
-*/
diff --git a/libgnucash/engine/gnc-numeric.h b/libgnucash/engine/gnc-numeric.h
index f08c0c5266..102270f3af 100644
--- a/libgnucash/engine/gnc-numeric.h
+++ b/libgnucash/engine/gnc-numeric.h
@@ -36,8 +36,6 @@
addition and multiplication, but 64-bit rationals do not have
the dynamic range of floating point numbers.
-See \ref gncnumericexample
-
@{ */
/** @file gnc-numeric.h
@brief An exact-rational-number library for gnucash.
commit 3c860737f1a74289513420d2393f9d84f6e9624b
Author: Geert Janssens <geert at kobaltwit.be>
Date: Sat May 18 17:20:15 2024 +0200
Doxygen - fold business.txt file in the respective source files
The file mostly had short descriptions that were very similar
to the descriptions of business objects it referred to. The
exception was an explanation of how the billing terms and
tax tables handled their immutable copies. That bit has been
moved to its own group under the Business group and is referenced
from the BillTerm and TaxTables group.
This commit also fixes rendering of the Address doxygen info
and expands the BillTerm info to explain how proximo due dates
work.
diff --git a/libgnucash/doc/CMakeLists.txt b/libgnucash/doc/CMakeLists.txt
index 3951484b85..dc33c60103 100644
--- a/libgnucash/doc/CMakeLists.txt
+++ b/libgnucash/doc/CMakeLists.txt
@@ -7,7 +7,6 @@ set(doc_FILES
backup.txt
books.txt
budget.txt
-# business.txt
callgrind.txt
constderv.html
# constraints.txt
diff --git a/libgnucash/doc/doxygen_main_page.c b/libgnucash/doc/doxygen_main_page.c
index 0d944760a4..d50603987e 100644
--- a/libgnucash/doc/doxygen_main_page.c
+++ b/libgnucash/doc/doxygen_main_page.c
@@ -32,7 +32,6 @@ in relation to existing code.
- \ref backuppolicy
- \ref bookperiods
-- \ref business1
- \ref currencies
- \ref deprecated
- \ref engine
diff --git a/libgnucash/engine/CMakeLists.txt b/libgnucash/engine/CMakeLists.txt
index dd9f63fb7c..3a5c3e4c4a 100644
--- a/libgnucash/engine/CMakeLists.txt
+++ b/libgnucash/engine/CMakeLists.txt
@@ -284,6 +284,7 @@ set(engine_EXTRA_DIST
README
README.query-api
SX-book-p.h
+ TaxTableBillTermImmutability.txt
)
if (NOT WIN32)
diff --git a/libgnucash/doc/business.txt b/libgnucash/engine/TaxTableBillTermImmutability.txt
similarity index 55%
rename from libgnucash/doc/business.txt
rename to libgnucash/engine/TaxTableBillTermImmutability.txt
index badd8521ad..0f55993028 100644
--- a/libgnucash/doc/business.txt
+++ b/libgnucash/engine/TaxTableBillTermImmutability.txt
@@ -1,45 +1,7 @@
-/** \page business1 Business Overview
-
-API: \ref Business
-
-\section businessoverview Business Objects
-
-The GnuCash Business objects, in src/business/business-core, implement
-certain basic small-business accounting functions. Below follows a summary
-overview of the objects and the data that they store. These are listed in
-order of complexity; with the basic building blocks first, and the more
-complex structures last.
-
-\subsection address Address:
-A very simple object, stores strings for name/street-address/phone/fax/email
-The address is not a separate entity, but is meant to be embedded in other
-objects (that is, there is no addressbook; there is no address database that
-is separate from the objects that use addresses; there is no 'foreach'
-that can be used to iterate over all addresses.)
-
-API: \ref Address
-
-\subsection billterm BillTerm:
-Describes billing terms, that is when a bill is due, and what sort of a
-discount is applied (if any). The BillTerm object currently supports:
--- the discount applied to a bill (absolute numeric value),
--- the number of days until payment is due,
--- the number of days until a discount expires.
--- cutoff ??
-The proximo type does what ???
-
-API: \ref BillTerm
-
-\subsection entry Entry:
-
-\subsection invoice Invoice:
-Pulls together info needed to generate an invoice, including addresses,
-job, the dates, the billing terms, the amounts, and the accounts
-to be credited.
-
-API: \ref Entry
-
-\section bus_design Business Design & Implementation Notes
+/**
+ \addtogroup Business
+ @{
+ \addtogroup ImmutableTaxTableBillTerm TaxTable and BillTerm immutability tracking
Derek Atkins <warlord at mit.edu>
Version of October 2003
@@ -77,5 +39,3 @@ explanation:
- A parent has a pointer to the current 'replica child', if one exists.
*/
-
-------------------------- end of file ------------------------------
diff --git a/libgnucash/engine/gncAddress.h b/libgnucash/engine/gncAddress.h
index 34db15eeb9..09421f9be5 100644
--- a/libgnucash/engine/gncAddress.h
+++ b/libgnucash/engine/gncAddress.h
@@ -22,27 +22,30 @@
/** @addtogroup Business
@{ */
/** @addtogroup Address
-
-An address belongs to another object, determined by the ::GncOwner.
-It is the owner that assigns a name and identifier to the address.
-In effect, an address is just a building - to make it useful to
-GnuCash, it needs to be tied to a person. After all, you cannot
-invoice a building, you invoice a person working / living in the
-building.
-
-QOF needs to handle all objects generically and to tie the address
-to an owner, QOF must be able to find each - as entities.
-
-This allows QOF to follow the hierarchy of objects without having
-to call any application-specific routines.
-
-To achieve this, new GncAddress routines have been added. An address
-is now created with a NULL parent and the parent set explicitly using
-the QOF object declaration. Whilst this adds functionality, it is
-important that a valid ::GncOwner entity is always set as a parent.
-This is an API issue - QOF will always set the parent provided that
-a suitable entity is passed to the qofAddressSetOwner routine. It is
-up to you to pass a suitable entity.
+ An address is a helper object used by the ::GncOwner object (and
+ its actual implementations ::GncCustomer, ::GncVendor and ::GncEmployee).
+
+ An address stores the physical address, phone, fax and email properties
+ of a ::GncOwner. The owner's name itself is stored in ::GncOwner.
+
+ @note an address is not a separate entity. It is meant to be embedded in other
+ objects (that is, there is no addressbook; there is no address database that
+ is separate from the objects that use addresses; there is no 'foreach'
+ that can be used to iterate over all addresses.)
+
+ QOF needs to handle all objects generically and to tie the address
+ to an owner, QOF must be able to find each - as entities.
+
+ This allows QOF to follow the hierarchy of objects without having
+ to call any application-specific routines.
+
+ To achieve this, new GncAddress routines have been added. An address
+ is now created with a NULL parent and the parent set explicitly using
+ the QOF object declaration. Whilst this adds functionality, it is
+ important that a valid ::GncOwner entity is always set as a parent.
+ This is an API issue - QOF will always set the parent provided that
+ a suitable entity is passed to the qofAddressSetOwner routine. It is
+ up to you to pass a suitable entity.
@{ */
/** @file gncAddress.h
diff --git a/libgnucash/engine/gncBillTerm.c b/libgnucash/engine/gncBillTerm.c
index 604786a4fa..9be71330dc 100644
--- a/libgnucash/engine/gncBillTerm.c
+++ b/libgnucash/engine/gncBillTerm.c
@@ -48,7 +48,7 @@ struct _gncBillTerm
gint cutoff;
/* Internal management fields */
- /* See src/doc/business.txt for an explanation of the following */
+ /* See libgnucash/engine/TaxTableBillTermImmutability.txt for an explanation of the following */
/* Code that handles this is *identical* to that in gncTaxTable */
gint64 refcount;
GncBillTerm * parent; /* if non-null, we are an immutable child */
diff --git a/libgnucash/engine/gncBillTerm.h b/libgnucash/engine/gncBillTerm.h
index ce8621ee9d..8c44e1b8ab 100644
--- a/libgnucash/engine/gncBillTerm.h
+++ b/libgnucash/engine/gncBillTerm.h
@@ -21,7 +21,44 @@
\********************************************************************/
/** @addtogroup Business
@{ */
-/** @addtogroup BillTerm
+/** @addtogroup BillTerm Billing Terms
+ Describes billing terms, that is when a bill is due, and what sort of
+ discount is applied (if any). The BillTerm object currently supports:
+ * the discount applied to a bill (absolute numeric value)
+ * the number of days until a discount expires
+ * information about the invoice due date
+
+ This last one can be defined in multiple ways:
+ * using a simple number of days value: the due date is posted date
+ incremented with this number of days
+ * using the "proximo" method which is explained below:
+
+ A proximo billing term has two parameters:
+ * due day: day of the month the invoice/bill will be due
+ * cutoff: day of the month used to decide if the due date will be
+ in the next month or in the month thereafter. This can be
+ a negative number in which case the cutoff date is relative
+ to the end of the month and counting backwards.
+ Eg: cutoff = -3 would mean 25 in February or 28 in June
+
+ How does it work:
+ Assume cutoff = 19 and due day = 20
+
+ * Example 1 post date = 14-06-2010 (European date format)
+ 14 is less than the cutoff of 19, so the due date will be in the next
+ month. Since the due day is set to 20, the due date will be
+ 20-07-2010
+
+ * Example 2 post date = 22-06-2010 (European date format)
+ 22 is more than the cutoff of 19, so the due date will be in the month
+ after next month. Since the due day is set to 20, the due date will be
+ 20-02-2010
+
+ @note A billing term added to an invoice is immutable, that is it
+ can't change any more. To achieve that a billing term is copied when
+ added to an invoice. This uses some internal fields to track this which
+ are explained in @ref ImmutableTaxTableBillTerm.
+
@{ */
/** @file gncBillTerm.h
@brief Billing Term interface
diff --git a/libgnucash/engine/gncBusiness.h b/libgnucash/engine/gncBusiness.h
index ecdd785fb4..aef11b0b33 100644
--- a/libgnucash/engine/gncBusiness.h
+++ b/libgnucash/engine/gncBusiness.h
@@ -20,8 +20,7 @@
/** @addtogroup Engine
@{ */
/** @addtogroup Business
- The Business Engine provides a set of structures for
- that provide small-business accounting features.
+ This module implements a number of basic small-business accounting functions.
@{ */
/** @file gncBusiness.h -- Business Helper Functions
diff --git a/libgnucash/engine/gncTaxTable.c b/libgnucash/engine/gncTaxTable.c
index 9ffd37720b..fec75d7aed 100644
--- a/libgnucash/engine/gncTaxTable.c
+++ b/libgnucash/engine/gncTaxTable.c
@@ -41,7 +41,7 @@ struct _gncTaxTable
GncTaxTableEntryList* entries;
time64 modtime; /* internal date of last modtime */
- /* See src/doc/business.txt for an explanation of the following */
+ /* See libgnucash/engine/TaxTableBillTermImmutability.txt for an explanation of the following */
/* Code that handles this is *identical* to that in gncBillTerm */
gint64 refcount;
GncTaxTable * parent; /* if non-null, we are an immutable child */
@@ -924,7 +924,7 @@ gboolean gncTaxTableEqual(const GncTaxTable *a, const GncTaxTable *b)
}
#if 0
- /* See src/doc/business.txt for an explanation of the following */
+ /* See libgnucash/engine/TaxTableBillTermImmutability.txt for an explanation of the following */
/* Code that handles this is *identical* to that in gncBillTerm */
gint64 refcount;
GncTaxTable * parent; /* if non-null, we are an immutable child */
diff --git a/libgnucash/engine/gncTaxTable.h b/libgnucash/engine/gncTaxTable.h
index d6b167e02f..4b0fe0affb 100644
--- a/libgnucash/engine/gncTaxTable.h
+++ b/libgnucash/engine/gncTaxTable.h
@@ -38,7 +38,7 @@ extern "C" {
/** @struct GncTaxTable
modtime is the internal date of the last modtime\n
-See src/doc/business.txt for an explanation of the following\n
+See libgnucash/engine/TaxTableBillTermImmutability.txt for an explanation of the following\n
Code that handles refcount, parent, child, invisible and children
is *identical* to that in ::GncBillTerm
Summary of changes:
.gitignore | 5 -
CMakeLists.txt | 12 +-
HACKING | 49 +-
README.dependencies | 7 -
bindings/guile/date-utilities.scm | 4 +-
bindings/python/gnucash_core.py | 129 +
doxygen.cfg.in | 2766 +++++++++++++++++++
.../doc/doxygen_main_page.c => doxygen_main_page.c | 95 +-
gnucash/gnome/window-autoclear.c | 2 +-
libgnucash/CMakeLists.txt | 1 -
libgnucash/backend/xml/CMakeLists.txt | 3 +-
.../{doc/xml => backend/xml/DTD}/CMakeLists.txt | 4 +-
libgnucash/{doc/xml => backend/xml/DTD}/README | 0
.../{doc/xml => backend/xml/DTD}/account-v2.dtd | 0
.../{doc/xml => backend/xml/DTD}/commodity-v2.dtd | 0
.../{doc/xml => backend/xml/DTD}/defaults-v1.dtd | 0
.../{doc/xml => backend/xml/DTD}/gnucash-v2.rnc | 0
.../xml => backend/xml/DTD}/io-gncxml-version1.dtd | 0
.../xml => backend/xml/DTD}/io-gncxml-version2.dtd | 0
.../xml => backend/xml/DTD}/preferences-v1.dtd | 0
.../{doc/xml => backend/xml/DTD}/prices-v1.dtd | 0
.../xml => backend/xml/DTD}/transactions-v2.dtd | 0
libgnucash/{doc/xml => backend/xml/DTD}/types.dtd | 0
libgnucash/doc/CMakeLists.txt | 45 -
libgnucash/doc/README | 4 -
libgnucash/doc/TODO-schedxactions | 584 ----
libgnucash/doc/TODO-sixtp | 33 -
libgnucash/doc/backup.txt | 38 -
libgnucash/doc/books.txt | 427 ---
libgnucash/doc/budget.txt | 225 --
libgnucash/doc/business.txt | 81 -
libgnucash/doc/callgrind.txt | 41 -
libgnucash/doc/constderv.html | 93 -
libgnucash/doc/constraints.txt | 98 -
libgnucash/doc/currencies.txt | 58 -
libgnucash/doc/design/CMakeLists.txt | 44 -
libgnucash/doc/design/component-manager.texi | 396 ---
libgnucash/doc/design/concept-index.texi | 4 -
libgnucash/doc/design/engine.texi | 2826 --------------------
libgnucash/doc/design/fdl.texi | 384 ---
libgnucash/doc/design/function-index.texi | 4 -
libgnucash/doc/design/gnucash-design.texi | 239 --
libgnucash/doc/design/intro.texi | 49 -
libgnucash/doc/design/register.texi | 162 --
libgnucash/doc/design/reports.texi | 95 -
libgnucash/doc/design/top-level.texi | 168 --
libgnucash/doc/design/type-index.texi | 4 -
libgnucash/doc/design/user-preferences.texi | 306 ---
libgnucash/doc/dia/components.dia | Bin 3346 -> 0 bytes
libgnucash/doc/dia/structures-alt.dia | Bin 3442 -> 0 bytes
libgnucash/doc/dia/structures.dia | Bin 3745 -> 0 bytes
libgnucash/doc/doxygen.cfg.in | 1853 -------------
libgnucash/doc/engine.txt | 45 -
libgnucash/doc/finderv.html | 337 ---
libgnucash/doc/finutil.html | 2278 ----------------
libgnucash/doc/g2-architecture.txt | 161 --
libgnucash/doc/generic-druid-framework.txt | 300 ---
libgnucash/doc/gnc-numeric-example.txt | 48 -
libgnucash/doc/guid.txt | 60 -
libgnucash/doc/loans.txt | 505 ----
libgnucash/doc/lots.txt | 522 ----
libgnucash/doc/multicurrency-discussion.txt | 281 --
libgnucash/doc/prices.txt | 37 -
libgnucash/doc/python-bindings-doxygen.py | 135 -
libgnucash/doc/qif.txt | 198 --
libgnucash/doc/sx.rst | 426 ---
libgnucash/doc/tax.txt | 21 -
libgnucash/doc/user-prefs-howto.txt | 63 -
libgnucash/engine/CMakeLists.txt | 2 -
libgnucash/engine/README | 12 +-
libgnucash/engine/SchedXaction.h | 290 ++
libgnucash/engine/Split.h | 4 +-
libgnucash/engine/Transaction.h | 2 -
libgnucash/engine/design.txt | 431 ---
libgnucash/engine/extensions.txt | 70 -
libgnucash/engine/gnc-date.h | 4 -
libgnucash/engine/gnc-lot.h | 513 +++-
libgnucash/engine/gnc-numeric.h | 2 -
libgnucash/engine/gnc-uri-utils.c | 22 -
libgnucash/engine/gnc-uri-utils.h | 48 -
libgnucash/engine/gncAddress.h | 45 +-
libgnucash/engine/gncBillTerm.c | 2 +-
libgnucash/engine/gncBillTerm.h | 39 +-
libgnucash/engine/gncBusiness.h | 41 +-
libgnucash/engine/gncTaxTable.c | 4 +-
libgnucash/engine/gncTaxTable.h | 9 +-
libgnucash/engine/kvp_doc.txt | 41 +-
libgnucash/engine/qofbook-p.h | 5 -
libgnucash/engine/qofquery.cpp | 43 +-
libgnucash/engine/qofquery.h | 7 -
libgnucash/engine/test/test-gnc-uri-utils.c | 4 +-
libgnucash/engine/xlate.pl | 272 --
libgnucash/gnc-module/CMakeLists.txt | 3 +-
libgnucash/gnc-module/README | 6 -
po/POTFILES.in | 1 -
95 files changed, 3918 insertions(+), 14759 deletions(-)
create mode 100644 doxygen.cfg.in
rename libgnucash/doc/doxygen_main_page.c => doxygen_main_page.c (66%)
rename libgnucash/{doc/xml => backend/xml/DTD}/CMakeLists.txt (72%)
rename libgnucash/{doc/xml => backend/xml/DTD}/README (100%)
rename libgnucash/{doc/xml => backend/xml/DTD}/account-v2.dtd (100%)
rename libgnucash/{doc/xml => backend/xml/DTD}/commodity-v2.dtd (100%)
rename libgnucash/{doc/xml => backend/xml/DTD}/defaults-v1.dtd (100%)
rename libgnucash/{doc/xml => backend/xml/DTD}/gnucash-v2.rnc (100%)
rename libgnucash/{doc/xml => backend/xml/DTD}/io-gncxml-version1.dtd (100%)
rename libgnucash/{doc/xml => backend/xml/DTD}/io-gncxml-version2.dtd (100%)
rename libgnucash/{doc/xml => backend/xml/DTD}/preferences-v1.dtd (100%)
rename libgnucash/{doc/xml => backend/xml/DTD}/prices-v1.dtd (100%)
rename libgnucash/{doc/xml => backend/xml/DTD}/transactions-v2.dtd (100%)
rename libgnucash/{doc/xml => backend/xml/DTD}/types.dtd (100%)
delete mode 100644 libgnucash/doc/CMakeLists.txt
delete mode 100644 libgnucash/doc/README
delete mode 100644 libgnucash/doc/TODO-schedxactions
delete mode 100644 libgnucash/doc/TODO-sixtp
delete mode 100644 libgnucash/doc/backup.txt
delete mode 100644 libgnucash/doc/books.txt
delete mode 100644 libgnucash/doc/budget.txt
delete mode 100644 libgnucash/doc/business.txt
delete mode 100644 libgnucash/doc/callgrind.txt
delete mode 100644 libgnucash/doc/constderv.html
delete mode 100644 libgnucash/doc/constraints.txt
delete mode 100644 libgnucash/doc/currencies.txt
delete mode 100644 libgnucash/doc/design/CMakeLists.txt
delete mode 100644 libgnucash/doc/design/component-manager.texi
delete mode 100644 libgnucash/doc/design/concept-index.texi
delete mode 100644 libgnucash/doc/design/engine.texi
delete mode 100644 libgnucash/doc/design/fdl.texi
delete mode 100644 libgnucash/doc/design/function-index.texi
delete mode 100644 libgnucash/doc/design/gnucash-design.texi
delete mode 100644 libgnucash/doc/design/intro.texi
delete mode 100644 libgnucash/doc/design/register.texi
delete mode 100644 libgnucash/doc/design/reports.texi
delete mode 100644 libgnucash/doc/design/top-level.texi
delete mode 100644 libgnucash/doc/design/type-index.texi
delete mode 100644 libgnucash/doc/design/user-preferences.texi
delete mode 100644 libgnucash/doc/dia/components.dia
delete mode 100644 libgnucash/doc/dia/structures-alt.dia
delete mode 100644 libgnucash/doc/dia/structures.dia
delete mode 100644 libgnucash/doc/doxygen.cfg.in
delete mode 100644 libgnucash/doc/engine.txt
delete mode 100644 libgnucash/doc/finderv.html
delete mode 100644 libgnucash/doc/finutil.html
delete mode 100644 libgnucash/doc/g2-architecture.txt
delete mode 100644 libgnucash/doc/generic-druid-framework.txt
delete mode 100644 libgnucash/doc/gnc-numeric-example.txt
delete mode 100644 libgnucash/doc/guid.txt
delete mode 100644 libgnucash/doc/loans.txt
delete mode 100644 libgnucash/doc/lots.txt
delete mode 100644 libgnucash/doc/multicurrency-discussion.txt
delete mode 100644 libgnucash/doc/prices.txt
delete mode 100644 libgnucash/doc/python-bindings-doxygen.py
delete mode 100644 libgnucash/doc/qif.txt
delete mode 100644 libgnucash/doc/sx.rst
delete mode 100644 libgnucash/doc/tax.txt
delete mode 100644 libgnucash/doc/user-prefs-howto.txt
delete mode 100644 libgnucash/engine/design.txt
delete mode 100644 libgnucash/engine/extensions.txt
delete mode 100755 libgnucash/engine/xlate.pl
delete mode 100644 libgnucash/gnc-module/README
More information about the gnucash-changes
mailing list