Readme updates. Started draft substitution field spec.

README.md

@@ -7,28 +7,26 @@
 
 ## What is gLabels-qt?
 
-gLabels-qt is the development repository for the next major version of gLabels (4.0).
+gLabels-qt is the development version of the next major version of gLabels (4.0).
 
 ![screenshot](docs/images/screenshot.png)
 
 
 ## What's new in gLabels-qt?
 
-- Based on the Qt cross-platform framework.
+- Based on the Qt5 framework.
 - Unlike previous versions, glabels-qt is a cross-platform application.
-  - So far, it has been built and tested under both Linux and Windows 7 (using MSYS/MINGW toolchain).
+    * So far, it has been built and tested under both Linux and Windows 7 (using MSYS/MINGW toolchain).
 - Updated UI based on typical workflows.
 
 
 ## Status
 
-gLabels-qt has been under off-and-on development since October 2013.
+gLabels-qt has been under off-and-on development for several years..
 It is still missing several features to bring it in parity with glabels-3.4.  These include
 
-- Barcode objects
-- Compatability with older glabels files
 - Batch mode
-- Internationalization
+- Compatability with older glabels files
 - Custom product templates designer
 - Online manual
 
@@ -64,11 +62,11 @@ expect compatability or consistency of features between snapshots.
 * Help is needed to add support to build and package glabels for various platforms and packaging systems.
 These include
 
-  - Windows (VisualStudio)
+    - Windows (VisualStudio)
-  - Windows (MINGW)
+   - Windows (MINGW)
-  - Mac
+   - Mac
-  - Linux (flatpak)
+   - Linux (flatpak)
-  - Linux (snap)
+   - Linux (snap)
 
 * Help is needed writing online documentation.
 

docs/IDEAS.md

@@ -1,76 +0,0 @@
-Ideas
-=====
-
-This file is simply a collection of ideas for future capabilities of glabels.
-The ideas may or may not be very well thought out -- it simply a scratchpad.
-
-
-Merge Fields
-------------
-
-Currently substitution fields are specified simply by `${field-name}`. Here, I
-am exploring ideas to extend this to be a richer substitution language.
-Some of the criteria to consider are:
-
- - A rich formatting capability probably cannot be done through GUI controls alone.
- - It should be simple and easy to understand, but also powerful.
- - Is there an existing language that can be used in whole or in part.
- 
-
-## Format Control
-It is desirable to control the format of the fields -- e.g. decimal, hex,
-number of digits, leading zeros, fixed width, left or right justification,
-etc.  Perhaps something like `${NAME:%-10s}`, i.e.
-`${field-name:printf-style-format}`.
-
-
-## Default Values
-It would also be desirable to specify a default value.  (Or an initial value
-in the event of a counter, see Label Counter below.)  Perhaps, something like
-`${field-name:=value}`
-
-
-## Possible Syntax
-This is the first stab at a syntax specification.  It is roughly based on
-the parameter substitution of the Bourne shell.
-
-```
-<field>     ::= "${" <field_name> [ ":" _modifiers_ ] "}"
-<modifiers> ::= <modifier> [ ":" <modifiers> ]
-<modifier>  ::= { "%" <format_spec> | "=" <value> }
-```
-
-Need a way to quote "`:`" in value.  Perhaps "`\:`" or maybe string values
-should always be in quotes (you would still need to quote out quotes.
-
-
-## Special Builtin Fields
-
-### Label Counter
-
-It would be nice if there was a label counter field.  Maybe something like
-`${#}` or `${label#}`.  Also desirable would be the ability to set the start
-value.  Possibly even reading it from a file and updating the file each time.
-You would want to control if the value is repeated for copies or every copy
-would be unique -- perhaps two different fields.  It would also be desirable to
-control the format of the counter -- e.g. decimal, hex, number of digits, or
-leading zeros.
-
-### Date and Time Fields
-
-Date and time fields would need to be able to be formatted much like strftime.
-
-
-## Examples
-Just some examples of the type of thing I am thinking.
-
-```
-${1}       /// CSV column 1
-${addr1}   /// Field named "addr1"
-${n:%09d}  /// Field named "n", format as 9 decimal digits with leading zeros
-${MI:=NMI} /// Field named "MI", with default value of "NMI"
-${#:%06d:=1000} /// Label counter, format as 6 decimal digits with leading zeros, starting at 1000
-${#:%06d:<count.txt:>count.txt}  /// Perhaps a way to read and write the starting and ending value
-
-```
-

docs/SUBSTITUTION-FIELD-SPEC.md

@@ -0,0 +1,85 @@
+DRAFT gLabels Substitution Field Specification
+==============================================
+
+> :warning: This is a very early draft specification.  There is no guarantee that any of the capabilities will be implemented as described in gLabels 4.0.  Prior to 4.0, this specification is subject to change.
+
+This specification describes gLabels substitution fields.  Substitution fields can be embedded in the data of gLabels text and barcode objects.  When printing, these fields are replaced with their respective values.  Fields can represent document merge fields or built-in variables. 
+
+Syntax
+------
+The general syntax of a substitution field is
+
+```ebnf
+substitution-field = "${", field-name, [ ":" modifiers ], "}" ;
+modifiers          = modifier, [ ":", modifiers ] ;
+modifier           = format-modifier | default-value-modifier ;
+```
+
+In its simplest and most common form, the format is simply `${ field-name }`.  For example `${FIRST_NAME}`.
+
+Modifiers
+---------
+### Format-Modifier (`%`)
+A format modifier is used to control the format of numerical and string values.  It is a subset of a single printf format placeholder.  Its syntax is
+
+```ebnf
+format-modifier = "%", [ flags ], [ width ], [ ".", precision ], type ;
+```
+
+#### Flags
+The Flags field can be zero or more (in any order) of:
+
+Character   | Description
+------------|------------
+`-` (minus) | Left-align the output of this placeholder. (the default is to right-align the output).
+`+` (plus)  | Prepends a plus for positive signed-numeric types. positive = `+`, negative = `-`. (the default doesn't prepend anything in front of positive numbers).
+` ` (space) | Prepends a space for positive signed-numeric types. positive = ` `, negative = `-`. This flag is ignored if the + flag exists. (the default doesn't prepend anything in front of positive numbers).
+`0` (zero)  | When the 'width' option is specified, prepends zeros for numeric types. (the default prepends spaces). For example, `${a:=3:%2X}` produces `3`, while `${a:=3:%02X}` produces `03`.
+
+#### Width
+The Width field specifies a minimum number of characters to output, and is typically used to pad fixed-width fields in tabulated output, where the fields would otherwise be smaller, although it does not cause truncation of oversized fields.
+
+#### Precision
+The Precision field usually specifies a maximum limit on the output, depending on the particular formatting type. For floating point numeric types, it specifies the number of digits to the right of the decimal point that the output should be rounded. For the string type, it limits the number of characters that should be output, after which the string is truncated.
+
+#### Type
+The Type field can be any of:
+
+Character | Description
+----------|--------------
+`d`, `i`  | integer value as a signed decimal number. %d and %i are synonymous.
+`u`       | integer value as an unsigned decimal number.
+`f`, `F`  | floating point value in normal (fixed-point) notation. f and F only differs in how the strings for an infinite number or NaN are printed (inf, infinity and nan for f, INF, INFINITY and NAN for F).
+`e`, `E`  | floating point value in standard form ([-]d.ddd e[+/-]ddd). An E c letter E (rather than e) to introduce the exponent. The exponent always contains at least two digits; if the value is zero, the exponent is 00.
+`g`, `G`  | floating point value in either normal or exponential notation, whichever is more appropriate for its magnitude. g uses lower-case letters, G uses upper-case letters. This type differs slightly from fixed-point notation in that insignificant zeroes to the right of the decimal point are not included. Also, the decimal point is not included on whole numbers.
+`x`, `X`  | integer value as an unsigned hexadecimal number. x uses lower-case letters and X uses upper-case.
+`o`       | integer value as an unsigned octal number.
+`s`       | string value.
+
+### Default-Value-Modifier (`=`)
+The default value modifier is used to set a default value for the field if its value is undefined.  It can also be used to set the initial value of some built-in variables, such as `${LABEL_NUMBER}`. Its syntax is
+
+```ebnf
+default-value-modifier = "=" value ;
+```
+
+Several characters must be backslash-escaped if they are included in value.  These are `:`, `}`, and `\`.
+
+Escape sequence | actual character
+----------------|-----------------
+`\:`            | colon `:`
+`\}`            | right bracket `}`
+`\\`            | backslash `\`
+
+Document Merge Fields
+---------------------
+Document merge fields are the primary source of substitution fields.  A document merge field represents a field from an external data source, such as a CSV file.
+
+Built-In Variables
+------------------
+### LABEL_NUMBER
+### PAGE_NUMBER
+### DATE
+### TIME
+### FILE_NAME
+