v3.6: products overhaul

New features, new documentation.

plugins/products.pod

@@ -0,0 +1,87 @@
+=head1 NAME
+
+products - RevBank plugin for selling products
+
+=head1 SYNOPISIS
+
+	8710447032756              0.80          Festini Peer
+	4029764001807,clubmate     1.40          Club-Mate +pf
+	pf                         0.15@+pfand   Pfand NRW-Flasche
+
+=head1 DESCRIPTION
+
+This plugin turns products from a product list into RevBank commands.
+
+The configuration for this plugin lives in a text file called
+C<revbank.products>, which has whitespace-separated columns:
+
+=head2 Product ids
+
+One or more product ids, separated by commas (no whitespace before or after the
+commas). There is no way to have a comma or whitespace in a product id, but
+every other printable character is valid.
+
+The first product id on the line is considered canonical, the rest are aliases.
+
+Note: if a product id is the same as another RevBank command (e.g. a username),
+the first plugin that accepts the command will "win"; the precedence order is
+defined by the C<revbank.plugins> configuration file. However, when a product
+id appears multiple times within C<revbank.products>, the I<last> one is used.
+
+Product ids that begin with C<+> can only be used as addons. When entered as
+user input, it will be ignored by the C<products> plugin.
+
+=head2 Price
+
+The price of the product. This is the price to be deducted from the user's
+account when they check out with this product in the cart. When it is a
+negative number, the user will instead have money added to their account when
+"buying" this product.
+
+Optionally, the price can be augmented with at C<@> sign and the name of the
+contra account. When no contra account is specified, C<+sales/products> is used.
+Internal accounts (that start with C<-> or C<+>) are created automatically. A
+regular account can also be used, but has to exist before the product can be
+used.
+
+(Note on internal accounts because they aren't documented elsewhere: liability
+and revenue accounts begin with C<+>, asset and expense accounts begin with
+C<->. The C<+> accounts typically grow larger over time, while C<-> accounts
+typically go negative. In general, you would use a C<+> account in
+C<revbank.products>. User accounts are liability accounts.)
+
+=head2 Description
+
+The description may contain whitespace.
+
+=head2 Addons
+
+Addons are products that are added as part of the main product. They are
+specified after the description, with a C<+> sign that has whitespace before
+it, and no whitespace after it.
+
+When specifying an addon C<+foo>, and no product with the id C<+foo> exists,
+the product id C<foo> is used instead. The difference is that a product id
+C<+foo> can only be used as an addon for another product, while C<foo> can be
+used either as an addon or a manually entered as a standalone product.
+
+	example_id          2.20     Example product +first +second
+	+first              1.20     First thing
+	second              0.80     Second thing
+
+In this example, the final price of the example product will be 4.20. It is not
+possible to buy the first thing separate, but it is possible to buy the second
+thing separate.
+
+The addon product must be specified in C<revbank.products>; market products
+cannot be used as addons.
+
+When a product has addons, it becomes a compound product. This can be used to
+separate a product into individual counter accounts for bookkeeping purposes,
+to add a bottle deposit, or to add other additional fees or discounts.
+
+When a compound product has a bare price that isn't 0.00, the bare price is
+listed as a component named "Product".
+
+A product can have multiple addons. Addon products themselves can also have
+further addons, but circular recursion is not supported.