[DOC]: barcodes: documentation

1 files changed, 56 insertions, 23 deletions

diff --git a/addons/barcodes/doc/index.rst b/addons/barcodes/doc/index.rst
index a6571597931..6cdacdc3a11 100644
--- a/addons/barcodes/doc/index.rst
+++ b/addons/barcodes/doc/index.rst
@@ -9,14 +9,63 @@ of items e.g. products, locations. It contains the following features:
 - Unlimited barcode patterns and definitions,
 - Barcode EAN13 encoding supported.
 
-Barcode nomenclatures and rules
--------------------------------
+Barcode encodings
+-----------------
 
-A barcode nomenclature contains a set of rules. Each rule identifies a barcode pattern. 
-A rule has a type specifying the model of the object whose barcode matches the pattern.
-A rule has an encoding as well, which can be either EAN-13, or Any. The encoding of a rule
-must be set to EAN-13 if the rule identifies a pattern matched by objects whose barcode is
-encoding in EAN-13. Rules have a sequence field indicated the order the rules are evaluated (ASC).
+A barcode is an arbitrary long sequence of ASCII characters. An EAN-13 barcode is a 13 digit
+barcode, whose 13th digit is the checksum. 
+
+Simple barcodes and rules
+-------------------------
+
+The default nomenclature assumes an EAN-13 encoding for product barcodes. It defines a rule 
+for Unit Products whose encoding is EAN-13, and whose pattern is '.', i.e. any barcode 
+matches this pattern. Scanning the barcode of a product, say '5410013101703', matches this rule. 
+The scanned item is thus identified as a Unit Product, and is retrieved from the product table.
+
+Note: the special character '.' in patterns is matched by any character. To explicitely specify 
+the '.' character in a pattern, escape it with '\'. The '\' character has to be escaped as well
+('\\') to be explicitely specified.
+
+Let us now suppose that we identify other items with barcodes, say stock locations. We define a
+new rule in the nomenclature with the corresponding type (in our example, the type is 'Location'),
+and whose pattern is e.g. '414.', that is, any location barcode starts with '414'. Scanning a barcode
+location, say '41401', matches this Location rule, and the corresponding location is retrieved from
+the location table.
+
+Note: Rules have a sequence field which indicates the order the rules are evaluated (ASC). In our 
+previous examples, the Unit Product rule should have a larger sequence that then Location rule, 
+because we want the latter one to be evaluated first.
+
+Barcodes with numerical content
+--------------------------------
+
+Barcodes may encode numerical content, which is decoded by the barcodes module. To that purpose,
+one have to define a new rule for barcodes with numerical content (e.g. barcodes for Weighted 
+Products). The numerical content in a pattern is specified between braces (special characters '{' and 
+'}'). The content of the braces must be a sequence of 'N's (representing the whole part of the numerical 
+content) followed by a sequence of 'D's (representing the decimal part of the numerical content). 
+For instance, let us define a new rule for Weighted Products whose pattern is '21.....{NNDDD}.'. Since
+we assume EAN-13 encoding for product barcodes, the encoding of this rule should be EAN-13 as well.
+
+Let us now assume that we want to write a barcode for a given Weighted Product, say oranges. We first 
+have to define in product oranges a barcode that will match the Weighted Product rule. This barcode 
+must start with '21' and be a correct EAN-13 barcode (i.e. the 13th digit must be a correct checksum). 
+Moreover, all the numerical content must be set to a '0'. For instance, let us set the barcode to 
+'2100001000004'. 
+
+We now want to write a barcode for 2.75kg of oranges. This barcode should be '2100001027506' (the 
+numerical content of this barcode is '02750', and the correct checksum is '6'). When scanned, this 
+barcode matches the Weighted Product rule (since is starts with '21'). The numerical content is extracted, 
+and replaced by a sequence of '0's. The correct checksum is then computed for the obtained barcode 
+('2100001000004') and the corresponding product (oranges) qgit is retrieved from product table.
+
+Note: the special characters '{' and '}' in patterns are used to identify numerical content. To 
+explicitely specify '{' or '}' in a pattern, they must be escaped.
+
+
+Strict EAN-13 field of barcode nomenclatures
+--------------------------------------------
 
 Many barcode scanners strip the leading zero when scanning EAN-13 barcodes. Barcode nomenclatures
 have a boolean field "Use strict EAN13". If False, when trying to match a scanned barcode with
@@ -24,19 +73,3 @@ a rule whose encoding is EAN-13, if the barcode is of length 12 and, by prependi
 the last digit is the correct checksum, we automatically prepend the barcode by 0 and try to
 find a match with this new barcode. If "Use strict EAN13" is set to True, we look for a pattern
 matching the original, 12-digit long, barcode.
-
-Barcodes and patterns syntax
------------------------------
-
-Barcodes and patterns may contain any character. Characters \ . { and } in patterns have a special
-meaning and thus have to be unspecialized (using \) to match their corresponding in barcodes. 
-For example, barcode "a1.b2{c3\d4" matches the pattern "a1\.b2\{c3\\d4". 
-
-Special character . in a pattern identifies any character (like in classical regular expressions).
-Patterns are automatically completed by ".*". For instance, the barcode "abcde" matches the 
-pattern ".bc". 
-
-Special characters { and } are used to identify numerical content. A pattern can contain at 
-most one set of { } and they must contain only N's and D's (N's represent the integer part of 
-the numerical content, while D's represent the decimal part). For instance, the barcode 
-"210025751" matches the pattern "21..{NNDD}." and encodes a value of 25.75.
\ No newline at end of file