Bug 129451 - Documentation for "hide section with condition" is misleading and unnecessarily complicated
Summary: Documentation for "hide section with condition" is misleading and unnecessari...
Status: RESOLVED WORKSFORME
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Documentation (show other bugs)
Version:
(earliest affected)
6.3.3.2 release
Hardware: All All
: medium normal
Assignee: sdc.blanco
URL:
Whiteboard:
Keywords:
Depends on:
Blocks: Section
  Show dependency treegraph
 
Reported: 2019-12-17 14:57 UTC by sdc.blanco
Modified: 2020-01-20 12:21 UTC (History)
4 users (show)

See Also:
Crash report or crash signature:
Regression By:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description sdc.blanco 2019-12-17 14:57:24 UTC
According to: 

https://help.libreoffice.org/6.4/en-US/text/swriter/guide/hidden_text.html?&DbPAR=WRITER&System=WIN

In the Hide area, select Hide, and then enter an expression in the Condition box. For example, using the variable you previously defined, enter Hide==1.

Test 1:

1.  Create a variable Hide (Insert > Fields > More Fields, Variables tab, Type "Set variable", Name "Hide", "Value" 0,  Insert)

2.  Create a section, Check Hide, put "Hide==1" in "With Condition"

Result:  Section is not hidden.   (Is it a bug or a documentation problem?)

Test 2:

3. Change value of Hide variable to 1

Result:  Section is Hidden


Test 3:

4.  Edit Section;  Change "With Condition"  to  "Hide==0"  (where Hide variable is still set to 1)

Result:  Section is shown.    (bug or documentation problem?)

Test 4:

5.  Set value of Hide variable to 0. (while leaving Hide==0 in the Section "With Condition")

Result:  Section is hidden  (i.e, the With Condition does not seem to have an effect)

Test 5:

6.  Set Variable to 0 and making Hide==1 in the "With Condition"

Result:   Section is not hidden.

Tests 4 and 5 do not seem consistent with the documentation at:

https://help.libreoffice.org/6.4/en-US/text/swriter/01/04020100.html?&DbPAR=WRITER&System=WIN

There may be more variations on this theme -- but perhaps these examples are enough to illustrate the problems -- where it is unclear what is intended, what is bug, and what is documentation problem.
Comment 1 Regina Henschel 2019-12-22 23:15:53 UTC
I do not understand your problem.

In step 2 the condition is "Hide==1" and the value of variable Hide is 0 from step 1. So the condition is false and the section is shown. The behavior is correct.
Comment 2 sdc.blanco 2019-12-23 00:22:01 UTC
(In reply to Regina Henschel from comment #1)
> I do not understand your problem.

Please note that this ticket was filed in relation to the documentation. 

I will try to explain again.

I.  Start with the information from: https://help.libreoffice.org/6.4/en-US/text/swriter/guide/hidden_text.html?&DbPAR=WRITER&System=WIN

where it says:

"In the Hide area, select Hide, and then enter an expression in the Condition box. For example, using the variable you previously defined, enter Hide==1."

Now -- I tried to do this -- *without* previously defining the variable Hide.

Putting the following into the Condition 
a. If Hide==1 then the section is shown.
b. If Hide==0 then the section is not shown.

(I now understand the logic here --  when Hide is not defined, it is like "0", so
case a.   0==1 (or any other non-zero value)is false, therefore show.
case b.   0==0  is true, so do not show.


I must explain that, in the first instance, I thought, naively, that I would just try Hide==1, like the documentation says (but without defining "Hide"), just to see what would happen.

Point 1:

I was surprised that:

a. I could get an effect, even though I had not defined Hide.   
b. that the effect was the opposite of what the documentation was suggesting.  

This raised a question for me about whether the documentation was adequate.


II. This experience motivated a new experiment, where now "Hide" would be defined as a variable. 

If I just put the variable Hide alone into the condition, then if Hide has value 0, it is shown, and value 1 then it is hidden.


Point 2.  If the "recommended" way to use the "With Condition" is with a predefined Hide variable, then why mention Hide==1 in the documentation, when this can be controlled "externally" so to speak by setting the Hide variable?

(It seems necessary only to put Hide, and then suggest that the variable value should be changed.)

III.  Now that I could see that I could control the section appearance with Hide alone, then I was curious about the interaction between the external variable and Hide==1 (in the "With Condition").

So -- please look at Test 5  (step 6) in the original report.

Thanks to your comment, I understand now why this result appears. But...

Point 3.  Notice how this example "contradicts" the help page.  Now we have put in Hide==1 but the section is not hidden.  Again my point is not the logic of what has happened in the software, but the confusion that is likely to arise with the way the help is written.  

I am reasonably certain that the documentation can/should be improved -- but was uncertain about a good/preferred way.  If you could help me with the formulation, then I can make the "commits" in the source.

Along the same lines, please look at https://help.libreoffice.org/6.4/en-US/text/swriter/01/04020100.html?&DbPAR=WRITER&System=WIN  

It has a slightly better discussion of the condition, but it also has:

"Another example would be to create the field variable "x" and set its value to 1. Then specify a condition based on this variable for hiding a section, such as: "x eq 1". If you want to display the section, set the value of the variable "x" to "0".

Again, it seems unnecessary (and confusing) to put "x eq 1" into the "With condition" -- as noted in Point 2,  it is enough to just change the field variable. 

In short, before I started this, I was a naive user, trying to understand how "With condition" works.  Now I am hoping to modify the documentation so that others can continue to be naive users, but can at least get some advantage from hiding sections (e.g., to hide answers to questions in a school paper), without having to become sophisticated about conditional logic.  I assume sophisticated users (who know about writing and using conditional expressions) will not need the documentation, while semi-sophisticated might be less confused with a more parsimonious explanation. 

Sorry for the length, but I hope this clarifies --
Comment 3 Olivier Hallot 2019-12-27 20:34:21 UTC
To answer the question in the subject line: the documentation is correct.
Comment 4 sdc.blanco 2019-12-28 17:17:58 UTC
(In reply to Olivier Hallot from comment #3)
> To answer the question in the subject line: the documentation is correct.

Ok -- will reformulate subject line and reopen.
Comment 5 Xisco Faulí 2020-01-20 12:00:35 UTC
You can't confirm your own bugs. Moving it back to UNCONFIRMED until someone
else confirms it.
Comment 6 sdc.blanco 2020-01-20 12:21:57 UTC
(In reply to Xisco Faulí from comment #5)
> You can't confirm your own bugs. Moving it back to UNCONFIRMED until someone
> else confirms it.
Sorry.  Was not my intention.  Did not understand meaning of REOPENED.

Anyway -- I have given up on this point, but here are my suggestions:
https://gerrit.libreoffice.org/c/help/+/86215