728910: Added more documentation for Budget Balance Sheet #327

datajunkie-eng · 2023-08-31T03:57:26Z

Here is a stab at some better documentation for the Budgeted Balance Sheet.

Here's what it looks like:

Current Version of the doc.

fellen

A nice amendment, thanks!
A few notes:

This is —like the previous report in that file— the technical description of the report. So they would belong into

gnucash-docs/C/manual/ch_Reports.xml

Line 3775 in cacf2e8

<sect2 id="report-budget">

Do you think,you can move them there and add here a link
[…] <ulink url="&url-docs-C;manual/report-classes.html#report-budget"><quote>Budget Reports</quote> in the manual</ulink>?
Ideally that is done in 2 commits
1. move the old report and add the link,
2. add your new report.
a few notes inline.

fellen · 2023-08-31T17:04:04Z

C/guide/ch_budgets.xml

+      <para>The Budgeted Balance Sheet is similar to the Balance Sheet (see <xref linkend="rpt_balancesheet"/>). Both show the assets, liabilities, and
+        equity. The difference is that the Balance Sheet is based on historical data, and the
+        <emphasis>budgeted</emphasis> balance sheet is based on the predictions made in the budget.  The report 


As we are formalizing the docs —see Text conventions— can you mark the first part as abstract and the description as glosslist?

<abstract><para>The <guilabel>Budgeted Balance Sheet</guilabel> is […] predictions made in the budget.</para></abstract> <para>The report contains the following elements: <glosslist> <title>Elements of Budgeted Balance Sheet</title> <glossentry> <glossterm>>Assets Section</glossterm> <glossdef> <para>The value shown for each account […] </para> </glossdef> </glossentry> … <glosslist>

See de/manual/ch_Tools_Assistants.xml for advanced usage of glosslists.

fellen · 2023-08-31T17:25:11Z

C/guide/ch_budgets.xml

+
+        <itemizedlist>
+        <listitem>
+          <para><emphasis>Assets Section</emphasis> - The value shown for each account is its balance as of the start date of the selected budget, modified by the projected changes in this budget.  So if all goes according to the budget, these balances would be the same as if you were to run a standard Balance Sheet as of the end date of the budget period.


After you finished your edts can you please run xmlformat over the file?
BTW runoff style (2 spaces after a full stop) is obsolete, but get also fixed by xmlformat.

fellen · 2023-08-31T21:42:39Z

C/guide/ch_budgets.xml

+        </listitem>
+
+        <listitem>
+          <para><emphasis>Total Liabilities + Equity</emphasis> - Liabilities + Equity.  Equals Total Assets


Perhaps use <equation> also here?

fellen · 2023-08-31T21:43:21Z

C/guide/ch_budgets.xml

+              <screen>
+          New Retained Earnings (all projected expenses subtracted from all projected income, per this budget) 
+        - Allocated Assets (above)
+        - New Liabilities</screen>


Screens are processed as verbatim. You don't want the indentation. Start in column 1.

BTW did you consider to use equation here and later?

This reverts commit 3648454.

datajunkie-eng · 2023-09-01T03:41:26Z

@fellen , I think I've addressed your feedback.

I'm not really liking how the equations are formatting:

Maybe there's an easy way to make them look better? I'll keep tinkering with it.

jralls · 2023-09-01T15:59:02Z

Equation 9.3

Use informalequation to get rid of the Equation XX titles. Those are for math textbooks.

But better to describe it in words, e.g. "The sum of existing equity and new equity". And "Total Liabilities + Equity: Total Liabilities + Equity" is redundant. Use "self explanatory" instead.

…section

datajunkie-eng · 2023-09-01T18:25:40Z

@jralls , yep, I like this better. Thanks!

fellen · 2023-09-01T19:52:13Z

C/manual/ch_Reports.xml

+                will show a $51/month gain instead of $100 (the projected assets/liabilities are
+                right). This formula is:
+                <informalequation>
+                  <mathphrase>Unallocated Assets = New Retained Earnings - Allocated Assets - New


Nitpick from Hyphens and dashes in Text conventions:
New Retained Earnings − Allocated Assets − New
There multiple other occurrences.

fellen · 2023-09-02T00:50:44Z

C/manual/ch_Reports.xml

@@ -3095,7 +3095,7 @@ Income (type INCOME)
                </listitem>

                <listitem>
-                  <para><guilabel>Report's currency</guilabel>: Select the currency to display the values in - see
+                  <para><guilabel>Report's currency</guilabel>: Select the currency to display the values in &minus; see


Caution, this should be — (— or enter [AltGr]+[Shift]+[-]).
In this case it is obvisious by the following see ….
[edit:] multiple occurrences

Much better to use the entity: It's both easier to enter (key combinations are localized and OS-specific) and especially in the case of — (U+2014), – (U+2013), −, (U+2011), and &hyphen; (U+2010, non-breaking U+2011) and the ASCII hyphen-dash (U+002d) that are hard to tell apart in source strings.

But I think it's better still to avoid using any of them except − in its arithmetic meaning because we want the documentation translated. Correct usage of the various dashes and hyphen in English can be so obscure that many native English speakers don't even know that there's a difference (it's wrong throughout this PR: − is for arithmetic and shouldn't be used in a sentence). Expecting non-native English speakers to correctly understand and translate them is asking a lot. em-dashes are usually a substitute for parentheses. That's the case here, so (see <xref linkend="report-common"/>) would be better.

Interesting, @jralls . There seems to be regional differences. In german books parentheses are used in formulas, but rarely in text.

We should try to find some consent and update the wiki section, which was written by an Australian IIRC.

Punctuation is very language specific. I wouldn't expect anything beyond full stops to transfer even between closely related languages like German, French, and English, never mind non-european ones. Even native speakers and writers of English have trouble with the finer points of punctuation, and there are lots of heated disputes about some practices, e.g. the Oxford comma. As it happens another hot dispute is how to set off a parenthetical expression. Sorry, I couldn't find a good reference for this, so here goes: The basic form that a lot of people think should be the only one is to use a pair of commas. The other inline choices are parentheses and em-dashes. One can also use footnotes or endnotes, an especially good idea if the aside will be lengthy.

The section in the wiki page about dashes just points to https://www.thepunctuationguide.com/index.html. I have no idea who wrote it but the sections are explanatory rather than style guidance. The flavor of English used by the original author doesn't seem important at least in that case.

@jralls and @fellen I'm fine continuing however you want with this bit of it, but I should mention that the changes outside the Budget Balance Sheet were inadvertent. I'd forgotten to limit the scope of my search/replace. Perhaps I should undo all these other changes? I'm not sure I want to be on the hook for this entire xml file at this time.

fellen · 2023-09-02T01:07:25Z

C/guide/ch_budgets.xml

@@ -206,7 +206,7 @@

      <para>The budgeted balance sheet is similar to the balance sheet. Both show the assets, liabilities, and
        equity. The difference is that the balance sheet is based on historical data, and the
-        <emphasis>budgeted</emphasis> balance sheet is based on the predictions made in the budget.
+        <emphasis>budgeted</emphasis> balance sheet is based on the predictions made in the budget.  For more details, see <ulink url="&url-docs-C;manual/report-classes.html#report-budget"><quote>Budget Reports</quote> in the manual</ulink>


IMHO most of the <sect1 id="budget_reporting1"> is still descriptive and belongs into the manual. Here I would expect rules to get the best results from using the reports like e.g. At first use report x to check for input errors. Some common rules are …

fellen · 2023-09-02T01:13:56Z

C/manual/ch_Reports.xml

@@ -359,8 +359,8 @@
        </listitem>

        <listitem>
-          <para>Maximum Slices: Controls the maximum number of slices displayed in a piechart - other accounts will
-            be placed in a slice marked Other.
+          <para>Maximum Slices: Controls the maximum number of slices displayed in a piechart &minus; other accounts


IMHO … in a piechart. All other accounts … is easier to understand.

fellen · 2023-09-02T01:18:10Z

C/manual/ch_Reports.xml

+          <glossentry>
+            <glossterm>Total Liabilities + Equity</glossterm>
+            <glossdef>
+              <para>Self Explanatory. This will equal Total Assets.


… if the book is balanced.

… if the book is balanced.

Always. The Balance Sheet Report gets a book into balance by inserting a calculated Equity account, Unrealized Gains (or Losses depending on whether Equity is less or greater than Assets - Liabilities) to balance an out-of-balance book. Everything else in the report exactly reflects the balances in the accounts at the end of the selected date.

fellen · 2023-09-02T01:26:49Z

C/manual/ch_Reports.xml

@@ -3843,81 +4015,83 @@ Income (type INCOME)

          <itemizedlist>
            <listitem>
-              <para><emphasis>Show budget</emphasis> - include the budgeted values for the period
+              <para><emphasis>Show budget</emphasis> &minus; include the budgeted values for the period


Do you think you can convert the itemzedlist into a glosslist and drop the -? It seems the original author did not know variablelist or glosslist and used it as separator between the term and its explanation.

@fellen, I think you're driving massive overuse of <glosslist>. As the docs say, "Using a GlossList in running text, instead of a VariableList, for example, maintains the semantic distinction of a Glossary. This distinction may be necessary if you want to automatically point to the members of the list with GlossTerms in the body of the text." A glossary is "a collection of textual glosses or of specialized terms with their meanings". That isn't even remotely related to what you're trying to use it for.

Well, this is my first review of a report. While in dialogs glosslists make sense because often one control depends on others. in reports the <variablelist> might be sufficient.

"variablelist — A list in which each entry is composed of a set of one or more terms and an associated description" (Heh, complete with a misused emdash!)
That's no more applicable than glosslist, not to dialogs and not to reports.

Plain old itemizedlist is generally the right choice, but only so far as a list is appropriate. E.g.

<section> <title>Assets</title> <para>The first section of the report lists the asset accounts, displayed hierarchically, with their balances projected to the end of the budget period. At the end of the section &app; will print the following totals: <itemizedlist> <listitem><title>Existing assets</title><para>Sum of all selected account balances at the beginning of the budget period. This is what a Balance Sheet Report would report as total assets for the same selected accounts on that date.</para>  </itemizedlist> </para> </section>

While glosslist and variablelist assign the wrong semantic meaning in this case, even trying to wrap bits of documentation in semantic tags is a relic of the 1990s. The semantic web fantasy didn't pan out. Stop wasting everyone's time and just focus on getting the right words in place with a reasonable layout.

fellen · 2023-09-02T02:10:40Z

a few more thoughts:

Are these reports sharing the same report options (as Budget Report)?
If not, add a options sections to the new reports;
If yes, should we move that report or at least its option section to the begin?
As most reports dislay a table, should we distinguish table rows and columns?
Should we add Screenshots? We can store an example data file for their generation in the data directory.

jralls · 2023-09-03T15:52:55Z

Apropos hyphens and dashes, using any of them in the form of Assets&pickyourdash;General is wrong. A colon would be better, but the repetition is tiresome and the layout obscures that Assets - General is a section header and the rest are summary lines at the end of that section. Laying the thing out as a glossary makes it even worse. @datajunkie-eng's original submission was very much better.

This reverts commit 3d1c049.

fellen · 2023-09-06T21:23:45Z

Apropos hyphens and dashes, using any of them in the form of Assets&pickyourdash;General is wrong. A colon would be better, but the repetition is tiresome and the layout obscures that Assets - General is a section header and the rest are summary lines at the end of that section. Laying the thing out as a glossary makes it even worse. @datajunkie-eng's original submission was very much better.

Right, the list should be split in groups Assets, Liabilities, Equity
and the group name should be dropped from their elements terms.
Perhaps the 3 lists should be wrapped into another list.

728910: Added more documentation for Budget Balance Sheet

3648454

datajunkie-eng mentioned this pull request Aug 31, 2023

728910: liabilities were adding as negative numbers Gnucash/gnucash#1755

Merged

fellen reviewed Aug 31, 2023

View reviewed changes

Jeff Shelley added 5 commits August 31, 2023 21:47

Revert "728910: Added more documentation for Budget Balance Sheet"

4c21d04

This reverts commit 3648454.

728910: Moved Budgeted Balance Sheet technical details to the manual

c92d073

728910: Better formatting

b02c254

728910: switched to use glosslist, more formatting

e645b23

728910: added link from guide to manual for Budget Balance Sheet

81c8a76

Jeff Shelley added 2 commits September 1, 2023 10:18

728910: clarified Unallocated Assets

3036732

728910: fixed xml typo

6c44090

728910: better formatting of equations, cleared up 'existing equity' …

af02c26

…section

fellen reviewed Sep 1, 2023

View reviewed changes

728910: turned - into − and dash into &hyphen;

3d1c049

fellen reviewed Sep 2, 2023

View reviewed changes

fellen mentioned this pull request Sep 5, 2023

L10n:de: manual: ch_Tools, section 'find transactions' #329

Merged

Jeff Shelley added 2 commits September 5, 2023 15:05

Revert "728910: turned - into − and dash into &hyphen;"

e3a3c3f

This reverts commit 3d1c049.

728910: turned some minuses into &minus, others into colons

e566836

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

728910: Added more documentation for Budget Balance Sheet #327

728910: Added more documentation for Budget Balance Sheet #327

datajunkie-eng commented Aug 31, 2023 •

edited

Loading

fellen left a comment

fellen Aug 31, 2023

fellen Aug 31, 2023

fellen Aug 31, 2023

fellen Aug 31, 2023

datajunkie-eng commented Sep 1, 2023

jralls commented Sep 1, 2023

datajunkie-eng commented Sep 1, 2023

fellen Sep 1, 2023

fellen Sep 2, 2023 •

edited

Loading

jralls Sep 3, 2023

fellen Sep 3, 2023 •

edited

Loading

jralls Sep 4, 2023

datajunkie-eng Sep 5, 2023

fellen Sep 2, 2023 •

edited

Loading

fellen Sep 2, 2023

fellen Sep 2, 2023

jralls Sep 3, 2023

fellen Sep 2, 2023

jralls Sep 4, 2023

fellen Sep 6, 2023

jralls Sep 6, 2023

fellen Sep 6, 2023

fellen commented Sep 2, 2023

jralls commented Sep 3, 2023

fellen commented Sep 6, 2023

728910: Added more documentation for Budget Balance Sheet #327

Are you sure you want to change the base?

728910: Added more documentation for Budget Balance Sheet #327

Conversation

datajunkie-eng commented Aug 31, 2023 • edited Loading

fellen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

datajunkie-eng commented Sep 1, 2023

jralls commented Sep 1, 2023

datajunkie-eng commented Sep 1, 2023

Choose a reason for hiding this comment

fellen Sep 2, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fellen Sep 3, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fellen Sep 2, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fellen commented Sep 2, 2023

jralls commented Sep 3, 2023

fellen commented Sep 6, 2023

datajunkie-eng commented Aug 31, 2023 •

edited

Loading

fellen Sep 2, 2023 •

edited

Loading

fellen Sep 3, 2023 •

edited

Loading

fellen Sep 2, 2023 •

edited

Loading