Bug 130072

Lack of documentation about variable formats.

https://help.libreoffice.org/6.5/en-US/text/swriter/01/04090005.html has a ”Format” item, but does not explain formats (or have a link from ”Format”) to a page that explains about formats.

Mike Kaganski has written an excellent tutorial about variable formats (in bug #84144 comment 6) and mentions these two help pages. 

[1] https://help.libreoffice.org/6.5/en-US/text/swriter/02/14020000.html
[2] https://help.libreoffice.org/6.5/en-US/text/swriter/01/04090200.html

(which he notes does not provide adequate documentation)

Searching on ”field variable” in Help did not reveal anything relevant beyond the above mentioned URLs.

The following text is copied (without change) from Mike’s excellent comment.  Perhaps this text (except for the last paragraph) could be used in a ”guide” page.  The last paragraph should be useful information though for the guide writer.    

(begin quote)

Inserting a "Set variable" field *for the first time*, you *define* a variable in the document; and also *define its type*, which can be *numeric* or *textual*. After the definition, you can't change the type (until you remove the variable from document using "cross" button in "Set variable" insertion dialog).

By default, all variables are created of numeric type.
Setting a variable's type is done by assigning it "Text" *format* when creating it.

When a variable is created numeric, i.e. not assigned "Text" format when created, its value is treated as a formula, and its result is converted to number. E.g., putting "is" with quotes would make the variable equal to result of conversion of text "is" to a number, which is 0. Putting "123a456" in quotes would result in number 123, because conversion to number stops at non-numeric character "a". `1+2` (without quotes) gives 3. Putting `pi` (without quotes) into the value of the numeric variable produces result of 3.14..., using one of predefined values [1] (note that value names are case-insensitive). When you have created a numeric variable varA with value 3, creating numeric varB with formula `varA + 1` will give 4.

For a numeric variable, there is a specific situation when you put an undefined name into its value box. E.g., creating numeric varA with value `is` without quotes, when no variable `is` was defined, produces varA variable with *empty* value, which e.g. also produces empty results of formulas like `varA + 1`.

When a variable is defined textual (by setting its format to Text upon its creation), anything you write into the value box is treated as plain string (except when you put an existing variable name); e.g., putting `is` without quotes into the value box (assuming there's no variable `is` predefined) will produce string "is", which might be tested using condition `var EQ "is"` [2]; putting "is" *with* quotes into the value box will produce 4-character string *containing the quotes*, so the condition `var EQ "is"` would fail this time; `1+2` would produce string "1+2". But when you have a variable txtA containing "AAA", and you create another textual txtB with value `txtA`, txtB will contain AAA.

Note again that trying to change existing variable type after creation will not work, neither in "Set variable field", nor in "Show variable", "Input field", or others.

The aspects of *creation* of a variable; *variables having a type*; and other variable manipulations (e.g., that variables don't get deleted when the last field setting/using it is removed; or inability to change type; or empty result when using undefined names in numeric variables; or using predefined variable names in textual variables) are unclear, not intuitive, and not well documented and represented in UI.