rock_books 0.7.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c30673728b99315fc841b99b96081751f91459663c736758b7340a317407cc56
-  data.tar.gz: 751adad9c6038a85a696deb4076bbc93bbfb8a8650d53159aca691b281388d9f
+  metadata.gz: 1a8a97b91bfab197a09e82f35e6561831edb0870e25c612344c98b262664bee4
+  data.tar.gz: 0dafb32fa34cf005ad0f2d967919ae00ff943fe11c5ab0326876172af2ce982d
 SHA512:
-  metadata.gz: 84ff76b2001eed18b4f4ec69f9949720a4dbca892f41a4fa6b96ddda9e19dde5660b34c514568f5410a117df8afddf84c33bf23ba31256efc2bceccbdb06bd01
-  data.tar.gz: 2214c3b52b24bf4b9b822059c4f41c67d7d3fc3a6fc666b8a073be79a794c769d1403d8f164085e382e1714320d71cbacd0673f591b26dd958e43f7b4cb1ab50
+  metadata.gz: bb122c867c07f9ec2ee5d7fc1b5951b90ee13eeb3472830660959588927ca20ddc84555240f197297d8a9d120970523872464dd6349ce05921d392c9c3f9d1f1
+  data.tar.gz: c5cdd3272ae72c67c28e011d4c57710289f78cd7b396a809c6875eb442d9665be23a2eb5f2ba54b2e4e61af9659ffb490ec83e80bdab80cb711708c40d771aed

data/{manual.md → MANUAL.md}

@@ -1,5 +1,7 @@
 # RockBooks Manual
 
+[[return to README](README.md)]
+
 
 | Note: |
 | ---- |
@@ -15,7 +17,7 @@ Install the RockBooks software:
 It is recommended that you create a directory structure such as this:
 
 ```.
-├── 2018-xyz-inc
+├── 2021-xyz-inc
 │   ├── invoices
 │   ├── receipts
 │   ├── references
@@ -25,28 +27,29 @@ It is recommended that you create a directory structure such as this:
 │   └── worksheets
 ```
 
-The top level is a directory containing your data for a given entity for a single reporting period (probably a year).
+The directory tree will contain your data for a given entity for a single reporting period (probably a year).
 
 Here are the subdirectories:
 
 * `rockbooks-inputs` - all input documents (chart of accounts, journals)
 * `rockbooks-reports` - all generated reports and web content
-* `receipts`
-* `invoices`
-* `references`
-* `statements`
-* `worksheets`
+* `receipts` - receipts and invoices from vendors
+* `invoices` - sales invoices (not invoices from vendors)
+* `statements` - downloaded statements from financial institutions, etc.
+* `worksheets` - supporting worksheets (e.g. for mileage allowances, meals and incidental allowances)
 
-The last five can contain your non-RockBooks specific files that you would normally keep anyway. These directories will be offered by the reports home page web interface merely to navigate the filesystem, with links to view the files using the default application for that file type. Receipts are handled specially though -- you can specify a receipt in a journal and it will be checked for existence in the Receipts report. In the future we hope to generate hyperlinks to both receipts and invoices in the journal reports.
+The last four can contain your non-RockBooks specific files that you would normally keep anyway. These directories will be offered by the reports home page web interface merely to navigate the filesystem, with links to view the files using the default application for that file type. Receipts and invoices are handled specially though -- you can specify a receipt or invoice filespec in a journal and its file will be linked to in the corresponding report transaction. In the Receipts report, receipts specified are checked for existence, and existing receipts files are checked for references in the journals; in the future we hope to do so for invoices as well.
 
 Feel free to organize your files in subdirectories of these directories in whatever way makes sense to you. I have subdirectories of `receipts` for each month (`01`, `02` ... `12`).
 
+In addition to the directories listed above, feel free to create other directories to organize your data. For example, you might want a `govt` directory for documents relating to business registration and licensing. Although there is no dedicated button for these additional directories on the data home page, you will be able to navigate to it with the `Browse All Data Files` button.
+
 
 ### Version Control
 
-Tracking this directory tree with version control software such as `git` in a private repository is _highly_ recommended because it provides:
+Tracking your data directory tree with version control software such as `git` is _highly_ recommended because it provides:
 
-* free cloud backup with Github, Gitlab, and/or Bitbucket
+* free cloud backup in a private repository with Github, Gitlab, and/or Bitbucket
 * an audit trail with human readable diffs
 * manageable collaboration
 
@@ -58,7 +61,7 @@ You will need a chart of accounts in the `rockbooks-inputs` directory. A sample
 
 ### Journals
 
-You will need journals. Usually there would be one journal per external financial institution accounts, such as checking and credit card accounts. Samples have been provided in the sample_data/minimal/rockbooks-inputs directory of the gem:
+You will need journals. Usually there would be one journal per external financial institution account, such as checking and credit card accounts. Samples have been provided in the sample_data/minimal/rockbooks-inputs directory of the gem:
 
 * [Checking](sample_data/minimal/rockbooks-inputs/2018-xyz-checking-journal.txt)
 * [Credit Card](sample_data/minimal/rockbooks-inputs/2018-xyz-visa-journal.txt)
@@ -92,10 +95,8 @@ Fields are space separated; any number of spaces can be used.
 
 #### Comment Lines
 
-Lines beginning with `#` will be ignored when the input data is parsed. Comment lines are useful for:
- 
-* explanations of the input itself
-* information that you would like to be available for deeper research or examination but not printed in the reports
+Lines beginning with `#` will be ignored when the input data is parsed. Therefore, comment lines will not be included in the generated reports. Comment lines are useful for explanations that are too verbose for the reports, but that should be available for deeper research. An example might be several lines of explanatory notes about an unusual transaction.
+
 
 #### Document Properties
 
@@ -110,19 +111,19 @@ as opposed to input records, will be expressed as lines beginning with `@`:
 
 #### Input Records
 
-Input records are multiple records for the type appropriate to the document:
+Input records are records of a type appropriate to the document:
 
 * chart of accounts - each account
 * journals - each transaction
 
-Input records are, in general, entered into the text files after all properties. One exception is that the `@date_prefix` is often specified in multiple places in the journal, usually with a new month (e.g. `@date_prefix: 2018-11`).
+Input records are, in general, entered into the text files after all properties. One exception is that the `@date_prefix` is often specified in multiple places in the journal, usually with a new month (e.g. `@date_prefix: 2021-11`).
 
 
 
 Data lines will contain fields that an be separated with an arbitrary number of spaces, e.g.:
 
 ```
-2018-05-18   123.45   supplies 
+2021-05-18   123.45   supplies 
 ```
 
 In journals, all entries will begin with dates, and all dates begin with numerals, so the
@@ -133,11 +134,11 @@ its other data and included in reports.
 
 In order to make the entry of dates more convenient, many documents will support
 a `@date_prefix` property that will be prepended to dates. For example, if this prefix
-contains `2018-`, then subsequent dates must exclude that prefix since it will be
+contains `2021-`, then subsequent dates must exclude that prefix since it will be
 automatically prepended. So, for example, a journal might contain the following lines:
 
 ```
-@date_prefix: 2018-
+@date_prefix: 2021-
 # ...more lines...
 05-29   37.50   ofc.spls
 05-30   22.20   tr.taxi
@@ -164,10 +165,10 @@ that will be used. Each account should contain the following fields:
 | ------------- | ------------- |
 | code          | a short string with which to identify an account, e.g. `ret.earn` for retained earnings
 | type          | 'A' for asset, 'L' for liability, 'O' for (owners) equity, 'I' for income, and 'E' for expenses.
-| name          | a longer more descriptive name, used in reports, so no more than 30 or so characters long is recommended
+| name          | a longer more descriptive name, used in reports, so no more than 30 or so characters long
   
 
-So, the chart of accounts data might include something like this:
+So, the chart of accounts data might include the following accounts:
 
 ```
 ck.xyz       A   XYZ Bank Checking Account
@@ -182,7 +183,7 @@ we recommend periods; they're much easier to type, and you'll be doing a _lot_ o
 
 There is no maximum length for account codes, and reports will automatically align based
 on the longest account code. However, keep in mind that you will need to type these codes,
-and they will consume space in reports.
+and they will consume valuable horizontal space in reports.
 
 For clarity, it is recommended that all accounts for each of the five account types be grouped together. That is, list all the assets first, then all the liabilities, etc.
 
@@ -236,9 +237,8 @@ the cash account), you would set the property to `debit`:
 
 #### General Journal
 
-The general journal is a special form of journal that does not have a primary account.
-
-In this journal, debits and credits need to be specified literally as account code/amount
+Since the general journal is a special form of journal that does not have a primary account, 
+debits and credits need to be specified literally as account code/amount
 pairs, where positive numbers will result in debits, and negative numbers will result in credits, e.g.:
 
 ```

data/README.md

@@ -1,14 +1,20 @@
 # RockBooks
+### A simple but useful free and open source accounting application for very small entities [[link]](https://github.com/keithrbennett/rock_books).
+#### Sponsored and Written by [Keith Bennett](https://github.com/keithrbennett) of [Bennett Business Solutions, Inc.](https://www.bbs-software.com)
 
-| Note: |
+| Other documentation files: |
 | ---- |
-| The [manual.md file](manual.md) has more detailed information about RockBooks usage. |
+| * [MANUAL.md](MANUAL.md) - more detailed information about RockBooks usage, especially setting up the data directory and inputting data. |
+| * [REPORTS.md](REPORTS.md) - viewing the generated reports |
+| * [RELEASE_NOTES.md](RELEASE_NOTES.md) |
 
-**A simple but useful accounting software application for very small entities.**
+The generated reports and supporting files can be submitted in the form of a zip file to an accountant, _who does not need any special software_ to view them...only a web browser.
 
 A supreme goal of this project is to give _you_ control over your data. Want to serialize it to YAML, JSON, CSV, or manipulate it in your custom code? No problem! 
 
-After entering the data in input files, there is a processing step (a single command) that is done to validate the input and generate the reports and home page. (This could be automated using `guard`, etc.) An `index.html` is generated that links to the reports, input documents, receipts, invoices, statements, worksheets, etc., in a unified interface. This `index.html` can be opened locally using a `file:///` URL but the directory tree can easily be copied to a web server for shared and/or remote access.
+After entering the data in input files, a single command validates the input and generates the reports and home page. A `rockbooks_reports/html/index.html` file is generated that links to the reports, input documents, receipts, invoices, statements, worksheets, etc., in a unified interface. This `index.html` can be opened locally using a `file:///` URL but the directory tree can easily be copied to a web server for shared and/or remote access. Here is an example page:
+
+![sample RockBooks data home page](assets/doc-images/sample-index-html.png "Sample RockBooks Data Home Page")
 
 #### How RockBooks Is Different
 
@@ -18,7 +24,7 @@ RockBooks is different in many ways.
 
 The software is in the form of Ruby classes and objects that can be incorporated into your own code for your own customizations. The data is available to programmers as Ruby objects (and therefore JSON, YAML, etc.) In addition, RockBooks could be used as an engine with alternate pluggable UI's. Feel free to write a web app for inputting the data!
 
-Rather than hiding accounting concepts from the user, RockBooks embraces and exposes them. There is no attempt to hide the traditional double entry bookkeeping system, with debits and credits. Accounting terminology is used throughout (e.g. "chart of accounts", "journals"). Some understanding of accounting or bookkeeping principles is helpful but not absolutely necessary.
+Rather than hiding accounting concepts from the user, RockBooks embraces and exposes them. There is no attempt to hide the traditional double entry bookkeeping system, with debits and credits. Accounting terminology is used throughout (e.g. "chart of accounts" and "journals"). Some understanding of accounting or bookkeeping principles is helpful but not absolutely necessary.
 
 To simplify its implementation, RockBooks assumes some conventions:
 
@@ -47,17 +53,17 @@ Instead of a web interface, data input is done in plain text files. This isn't a
 
 * Users can use their favorite text editors.
 
-* All data entry can be done without moving the hands away from the keyboard.
+* All data entry can be done without moving the hands away from the keyboard (assuming the editor software supports it, as does `vim`).
 
 
 #### The Accounting Period
 
-There is no handling of end of year closings or the like; the entire set of data in the input files is considered included in the reporting period when generating the reports. Therefore, the best approach is to create a new data set for each year. The chart of accounts and journal files can be copied and modified as necessary.
+There is no handling of end of year closings or the like; the entire set of data in the input files is considered included in the reporting period when generating the reports. Therefore, the best approach is to create a new data set for each year. The chart of accounts and journal files can be copied from the previous year and modified as necessary.
 
 #### RockBooks Help Text
 
 ```
-Command Line Switches:                    [rock-books version 0.2.1 at https://github.com/keithrbennett/rock_books]
+Command Line Switches:                    [rock-books version 0.11.0 at https://github.com/keithrbennett/rock_books]
 
 -i   input directory specification, default: './rockbooks-inputs'
 -o   output (reports) directory specification, default: './rockbooks-reports'
@@ -66,14 +72,13 @@ Command Line Switches:                    [rock-books version 0.2.1 at https://g
 
 Commands:
 
-rec[eipts]                - receipts: a/:a all, m/:m missing, e/:e existing
+rec[eipts]                - receipts: a/:a all, m/:m missing, e/:e existing, u/:u unused
 rep[orts]                 - return an OpenStruct containing all reports (interactive shell mode only)
-d[isplay_reports]         - display all reports on stdout
 w[rite_reports]           - write all reports to the output directory (see -o option)
 c[hart_of_accounts]       - chart of accounts
 h[elp]                    - prints this help
 jo[urnals]                - list of the journals' short names
-proj[ect_page]            - open the RockBooks Github project page in a browser
+proj[ect_page]            - prints the RockBooks Github project page URL
 rel[oad_data]             - reload data from input files
 q[uit]                    - exits this program (interactive shell mode only) (see also 'x')
 x[it]                     - exits this program (interactive shell mode only) (see also 'q')
@@ -88,11 +93,14 @@ When in interactive shell mode:
 
 ## What RockBooks Is Not
 
-As a product written by a single developer in his spare time, RockBooks lacks some conveniences of traditional accounting software programs, such as:
+As a product written by a single developer in his spare time, 
+RockBooks lacks many conveniences of traditional accounting software programs, such as:
 
 * Import of data from financial institutions
 * On the fly data validation
 * Data entry conveniences such as drop down selection lists for data such as accounts
+* Tracking of receivables and payables (other than generating the standard report set)
+* Aggregation of sub-accounts, such as aggregating separate receivable accounts for each client
 * Fancy reporting and graphing -- however, RockBooks' bringing links to all the entity's documentation and output into a single web page may well be more useful
 
 

data/RELEASE_NOTES.md

@@ -1,3 +1,48 @@
+# Release Notes
+
+[[go to README](README.md)]
+
+### v0.11.0
+
+* Add and fix documentation, especially addition of REPORTS.md about viewing the generated reports.
+* Add "Original Input Documents" and "Browse All Data Files" buttons to generated index.html.
+
+
+### v0.10.0
+
+* Add invoice hyperlinks to generated HTML.
+* Improve documentation.
+* Add progress bar to report generation.
+* Change 'proj[ect]' command to print the project home page URL, rather than call `open` on it. This makes the command useful in more cases and removes environment dependency.
+* Remove interactive 'display reports' option. It's not that useful and easy enough to write all reports to disk and selectively view them.
+* Fix rep[orts] interactive option.
+* Fix and refactor handling of receipt data on command line.
+* Add styling to report HTML pages, mostly for centering the reports, increasing the font size, and providing a faint blue background.
+
+
+### v0.9.0
+
+* Center generated index.html's content.
+* Improve report headings.
+* Fix index.html hyperlinks to resource (receipts, invoices, statements, worksheets) directories.
+* Fix cases where split journal entries were not included in the journal report.
+
+
+### v0.8.0
+
+* Add metadata to PDF and HTML reports
+* Add report generation timestamp and accounting period to all reports.
+* Refactoring and cleanup.
+
+
+### v0.7.1
+
+* Refactor report helpers. 
+* Improve/reduce text output during reporting.
+* Add title to HTML reports.
+* Minor fixes.
+
+
 ### v0.7.0
 
 * Dependencies on external commands in Linux and Mac OS for generating PDF and HTML files has been eliminated,
@@ -23,7 +68,7 @@ using the prawn gem for PDF and simple ERB templating for HTML.
 * Add receipt hyperlinks to HTML output.
 
 
-## v0.4.0
+### v0.4.0
 
 * Sort unused receipts alphanumerically.
 * Add 'x' receipts option for reporting both missing and unused receipts.
@@ -31,7 +76,7 @@ using the prawn gem for PDF and simple ERB templating for HTML.
 * Improve Receipts report.
 
 
-## v0.3.0
+### v0.3.0
 
 * Added ability to report unused receipts.
 * Errors now include more context information.
@@ -39,12 +84,12 @@ using the prawn gem for PDF and simple ERB templating for HTML.
 * Change license from MIT to Apache 2.
 
 
-## v0.2.1
+### v0.2.1
 
 * Add help text to readme.
 
 
-## v0.2.0
+### v0.2.0
 
 * Add instruction manual, modify readme.
 * Overhaul generated index.html.
@@ -52,18 +97,18 @@ using the prawn gem for PDF and simple ERB templating for HTML.
 * Add validation of transaction dates to ensure within configured date range.
 * Make report hash / OpenStruct keys consistently symbols.
 
-## v0.1.6
+### v0.1.6
 
 * Fixed PDF output; PDF files were corrupt because cupsfilter starting sending
 output to stderr at some point.
 
 
-## v0.1.4, v0.1.5
+### v0.1.4, v0.1.5
 
 * Intermediate unsatisfactory fixes, these versions were published but yanked. 
 
 
-## v0.1.3
+### v0.1.3
 
 * Report output now goes to separate txt, html, and pdf subdirectories.
 * Add vendor.yml to exclude generated report files from language reporting.
@@ -78,17 +123,17 @@ output to stderr at some point.
 * Add 'from_string' methods to Journal and ChartOfAccounts.
 
 
-## v0.1.2
+### v0.1.2
 
 * Improve error message when the needed directories do not exist. 
 
 
-## v0.1.1
+### v0.1.1
 
 * Fix startup error.
 
 
-## v0.1.0
+### v0.1.0
 
 * First release.
 

data/REPORTS.md

@@ -0,0 +1,81 @@
+# Viewing the RockBooks Generated Reports
+
+[[return to README](README.md)]
+
+[Note to Accountants: Your client may send their tax information to you in the form of a zip file.
+In order for the web links to work, it is necessary to unzip this file onto your system.
+(That is, it is not enough to just click into the zip file in a file explorer.)]
+
+## Viewing the Data
+
+To view the generated reports and their supporting documents, you will need to open the file
+`rockbooks_reports/html/index.html`. Using a file explorer (e.g. _Explorer_ on Windows or _Finder_ on Mac)
+you can double-click `rockbook-reports`, then double-click `html`, then double-click `index.html`.
+This should bring up a page looking something like this:
+
+![sample RockBooks data home page](assets/doc-images/sample-index-html.png "Sample RockBooks Data Home Page")
+
+## ! Important Security Warning !
+
+The generated HTML files are intended for local and individual use only. For your convenience, they contain links that enable you to navigate your data directories, but also your entire file system. _Making your files accessible via a web server or screen sharing would enable the remote user to view all the files on your system and is not recommended!_ You can give others access to your files safely by instead sending them only the data files, most conveniently in the form of a zip file.
+
+## Initially Submitted Data is Not Necessarily Final
+
+When you initially submit your data to your accountant, he or she may offer corrections and suggestions. Be prepared to regenerate the reports after making any changes. It's easy to do; in a terminal, run `rock_books w` in the project data directory.
+
+Assuming the accountant wants a zip file, in a terminal, run `zip -r my-data.zip .` (although this would work, it's probably better to specify the zip file in a different directory, e.g. `zip -r ~/temp/my-data.zip .`,  so that you don't include other backups in your backup). Alternatively you could use a GUI application to do the same. (In order to keep track of multiple versions of the data, I suggest including the date/time in the filename, e.g. `2021-01-25_17-32-02_2020-bbs-data.zip`.) 
+
+
+## Supporting Documents
+
+The "Supporting Documents" buttons merely link you to the corresponding directories extracted from the zip file. The "Original Input Documents" are the text files in which the client has recorded the transactions.
+
+## Invoices and Receipts
+
+There are buttons with which you can navigate the invoices and receipts directory trees (i.e. folders and subfolders). This can be useful, but the reports should contain appropriate links to invoices and receipts _per transaction_, and this might be how you prefer to view them.
+
+## Beginning Account Balances
+
+Currently the software does not differentiate between an account's initial balance and a transaction on the first day of a period. That is, there is no implementation of beginning balances; one simulates this by recording a transaction in the general journal on January 1st.
+
+## HTML, PDF, and Text Formats
+
+The simplest and most productive way to view the data is opening its `index.html` page in a web browser, but each report is also provided in text and PDF formats, in case that might be useful to you.
+
+## Browsing the Files
+
+If you want to view files _in addition to_ those already available with other buttons, you can click the `Browse` button next to `Browse All Data Files` at the bottom of the home page. This will display a listing of the data directory from its top. Here is a sample RockBooks data directory tree:
+
+```
+├── govt
+├── invoices
+├── misc
+├── receipts
+│   ├── 01
+│   ├── 02
+│   ├── 03
+│   ├── 04
+│   ├── 05
+│   ├── 06
+│   ├── 07
+│   ├── 08
+│   ├── 09
+│   ├── 10
+│   ├── 11
+│   └── 12
+├── rockbooks-inputs
+├── rockbooks-reports
+│   ├── html
+│   │   └── single-account
+│   ├── pdf
+│   │   └── single-account
+│   └── txt
+│       └── single-account
+├── statements
+│   ├── pnc-checking
+│   ├── pnc-visa
+│   └── southwest-visa
+└── worksheets
+```
+
+As an example of a useful directory that is not accessible via the other buttons, you can see a `govt` directory. This might be where the client has stored documents relating to business registration, licenses, etc.