[Gnumed-devel] Placeholder clarifications - nomenclature, syntax and rules

[Busser, Jim]

Is the following sane and, in either case, please suggest any clearer way to 
correct and properly express it:


(1) every GNUmed placeholder must be bounded by a pair of dollar symbols $ 
within which must exist a pair of angles brackets, thus:

        $<>$

(2) between the $<>$, the simplest placeholder expects and supports a single 
'field', whereas those placeholders which support a second and third field 
require a separator (delimiter) after the first field, in the form of a pair of 
colons, thus:

        ::

as a result of which, a placeholder which supports three fields would have the 
form

        $<field_1 :: field_2 :: field_3>$

wherein

        field_1 must, in all cases, provide a valid (defined-in-GNUmed) 
placeholder name

        field_2 provides for one (or a series of) argument(s) which, in some – 
but not all cases – need to be supplied

        field_3 provides for an ability, or a requirement, to specify a maximum 
number (length) of target characters

and

        field_1 cannot be followed solely by a single pair of ::

In other words, while field_1 can, in some cases, be complete as

        $<field_1>$

it cannot be

        $<field_1::field_2>$

but must include

        $<field_1::::>$

even if the '::' remain "empty".

Lastly, those placeholders which do not require the third field (max num of 
characters) nevertheless, in all cases, support the third field to be included, 
whether the value within is null (empty) or whether it consists of a valid 
integer. Thus you can have $<field_1:::integer:>$ or you can have 
$<field_1::::>$ (which is the same as $<field_1>$).

Spaces, such as might make a placeholder's incarnation more readable, are not 
harmless. Within a placeholder, spaces – except when part of a valid and 
properly formatted argument – will break the placeholder, as in

        $< field_1::::60 >$.

In the situation where a properly-formatted placeholder cannot resolve to a 
value, such as in the case where no value had yet been created for a patient, 
the resulting output will depend whether or not the instance of GNUmed is 
running with --debug on. If yes, it will return "no URL for …" and otherwise 
u'' (IOW, an empty value).

-- Jim