[Libreoffice-bugs] [Bug 130072] New: Need documentation about field variable formats

[bugzilla-daemon at bugs.documentfoundation.org]

https://bugs.documentfoundation.org/show_bug.cgi?id=130072

            Bug ID: 130072
           Summary: Need documentation about field variable formats
           Product: LibreOffice
           Version: 6.3.4.2 release
          Hardware: All
                OS: All
            Status: UNCONFIRMED
          Severity: normal
          Priority: medium
         Component: Documentation
          Assignee: libreoffice-bugs at lists.freedesktop.org
          Reporter: sdc.blanco at youmail.dk
                CC: olivier.hallot at libreoffice.org

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.

-- 
You are receiving this mail because:
You are the assignee for the bug.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/libreoffice-bugs/attachments/20200118/d590f92b/attachment-0001.htm>