rock_books 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 974a379630080a4b8ec174d0b79fe46ce629f0c0fab0c6e147e3b1e4cd472c3f
-  data.tar.gz: 289a1cccf88c3ab27fccac9bfd98c9b4e88f4d14d791d92ebcf52dfd6d7509ee
+  metadata.gz: 1a8a97b91bfab197a09e82f35e6561831edb0870e25c612344c98b262664bee4
+  data.tar.gz: 0dafb32fa34cf005ad0f2d967919ae00ff943fe11c5ab0326876172af2ce982d
 SHA512:
-  metadata.gz: 57489817b4cae0dd70db00ee4fc10f8fc432ebb1a6ed01a93b6c1f646b681ae5eb456d171c5a7fe2d981bada1771da33eccba7ed08cebceee57925c5c1bb7560
-  data.tar.gz: 2f530db52499773bae28f24f6ee4cf0a243056b6e8df9a83723826b132b4cecc558451bcf357840946e437e6e22740aa4b7d417789df84ec3bbba6050917fe57
+  metadata.gz: bb122c867c07f9ec2ee5d7fc1b5951b90ee13eeb3472830660959588927ca20ddc84555240f197297d8a9d120970523872464dd6349ce05921d392c9c3f9d1f1
+  data.tar.gz: c5cdd3272ae72c67c28e011d4c57710289f78cd7b396a809c6875eb442d9665be23a2eb5f2ba54b2e4e61af9659ffb490ec83e80bdab80cb711708c40d771aed

data/{manual.md → MANUAL.md}

@@ -1,5 +1,7 @@
 # RockBooks Manual
 
+[[return to README](README.md)]
+
 
 | Note: |
 | ---- |
@@ -25,26 +27,27 @@ 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` 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 in a private repository with Github, Gitlab, and/or Bitbucket
 * an audit trail with human readable diffs
@@ -162,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
@@ -180,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.
 

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:
 
@@ -57,7 +63,7 @@ There is no handling of end of year closings or the like; the entire set of data
 #### RockBooks Help Text
 
 ```
-Command Line Switches:                    [rock-books version 0.10.0 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'
@@ -93,6 +99,8 @@ RockBooks lacks many conveniences of traditional accounting software programs, s
 * 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,13 @@
+# 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.

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.

data/lib/rock_books/reports/templates/html/index.html.erb

@@ -34,6 +34,10 @@
         color: #01182d;
         border: 0px;
       }
+
+      .lower_button_width {
+          min-width: 100px;
+      }
     </style>
   </head>
 
@@ -72,6 +76,7 @@
       <%= subdir_link.('receipts',   'Receipts')   %>
       <%= subdir_link.('statements', 'Statements') %>
       <%= subdir_link.('worksheets', 'Worksheets') %>
+      <%= subdir_link.('rockbooks-inputs', 'Original Input Documents') %>
     </div>
 
 
@@ -89,7 +94,7 @@
         <div class="row">
 
           <div class="col-sm2" style="margin-right: 12px;">
-            <a class="btn btn-primary" data-toggle="collapse" href="#{href}" role="button" aria-expanded="false" aria-controls="collapseExample">
+            <a class="btn btn-primary lower_button_width" data-toggle="collapse" href="#{href}" role="button" aria-expanded="false" aria-controls="collapseExample">
               +/-
             </a>
           </div>
@@ -154,5 +159,22 @@
       </div>
     </div>
 
+
+    <br /><br />
+
+    <div class="container-fluid">
+      <div class="row">
+
+        <div class="col-sm2" style="margin-right: 12px;">
+          <a class="btn btn-primary lower_button_width" href="../..">
+            Browse
+          </a>
+        </div>
+
+        <div class="col-sm10">
+          <h2 style="margin: 0px;">Browse All Data Files</h2>
+        </div>
+      </div>
+    </div>
   </body>
 </html>

data/lib/rock_books/version.rb

@@ -1,4 +1,4 @@
 module RockBooks
-  VERSION = '0.10.0'
+  VERSION = '0.11.0'
   PROJECT_URL = 'https://github.com/keithrbennett/rock_books'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rock_books
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Keith Bennett
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-01-25 00:00:00.000000000 Z
+date: 2021-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: amazing_print
@@ -136,9 +136,12 @@ files:
 - ".travis.yml"
 - Gemfile
 - LICENSE.txt
+- MANUAL.md
 - README.md
 - RELEASE_NOTES.md
+- REPORTS.md
 - Rakefile
+- assets/doc-images/sample-index-html.png
 - assets/fonts/JetBrainsMono-Medium.ttf
 - bin/console
 - bin/setup
@@ -196,7 +199,6 @@ files:
 - lib/rock_books/types/acct_amount.rb
 - lib/rock_books/types/journal_entry_context.rb
 - lib/rock_books/version.rb
-- manual.md
 - rock_books.gemspec
 - sample_data/minimal/receipts/01/2018-01-01-sample-receipt.jpg
 - sample_data/minimal/rockbooks-inputs/2018-xyz-chart-of-accounts.txt