Bug 149253 - Anchor help pages needs some improvement
Summary: Anchor help pages needs some improvement
Status: RESOLVED FIXED
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Documentation (show other bugs)
Version:
(earliest affected)
7.4.0.0 alpha0+
Hardware: All All
: medium normal
Assignee: Not Assigned
URL:
Whiteboard: target:7.4.0
Keywords:
: 132864 (view as bug list)
Depends on:
Blocks: Anchor-and-Text-Wrap Help
  Show dependency treegraph
 
Reported: 2022-05-24 02:18 UTC by sdc.blanco
Modified: 2022-10-13 11:51 UTC (History)
5 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 2022-05-24 02:18:15 UTC
Copied from bug 132864 comment 18

(In reply to Heiko Tietze from comment #10)
> What is missing at the documentation?
> 
> https://help.libreoffice.org/latest/en-US/text/shared/01/05260000.html
"To page" could be clarified

"As character" is not correct about height of current line.  (or, correct only under certain, but not all, circumstances).

> https://help.libreoffice.org/latest/en-US/text/swriter/guide/anchor_object.
> html?DbPAR=WRITER#bm_id3147828
First sentence (and rest of page) is missing critical information about positioning options.
Comment 1 Telesto 2022-05-24 08:21:38 UTC
*** To page ***
https://help.libreoffice.org/latest/en-US/text/shared/01/05260000.html

To page anchors the object to the physical page in the document where the object currently appears.

------------
I read physical as: tangible, concrete; having to do with the material world

I'm not an expert in writing manuals. An attempt to how I conceptualize it. 'To Page anchors the object to exact page where it inserted to. The image isn't linked to text flow/ The image doesn't follow the text flow. 

***To Character***
> https://help.libreoffice.org/latest/en-US/text/swriter/guide/anchor_object.
> html?DbPAR=WRITER#bm_id3147828

First sentence (and rest of page) is missing critical information (which is also highly relevant to the discussion in this ticket). Here is first sentence.

    An object, such as an image, is positioned within a document using
    anchors attached to other elements.

It is true that anchors "are used" -- but what is missing in that guide is:

    It is also *necessary* to specify the positioning options in relation to 
    the anchor point.  

Simply mentioning the anchoring being used, without specifying the positioning options is more or less impossible to evaluate what will happen with a particular object when text or objects are added or removed from the document.
(and there are additional complications -- but they can be, in principle, addressed in other help pages)

----
The Help surely lacking critical information.. However to specify the positioning options in relation to the anchor point bit of a thing.

This does happen if you insert the image to say a 3x3 table. Select the image, hovering over the anchor and press and hold left click and drag around horizontally or vertically.

However in other cases it doesn't, in my view. Have 3 dummy paragraphs. And place the image at the third paragraph aligned at right. Drag the anchor horizontally: doesn't change anything to the position of the image

Vertically doesn't change anything either, except if you drag it to different paragraph, in that case the position of the image changes

Anchor the image (still to character) at the beginning of the first paragraph. And drag the image (not the anchor) to the second of third paragraph. Notice the anchor picking some totally different anchor point. So distance between anchor and image changing.
Comment 2 sdc.blanco 2022-05-24 12:30:11 UTC
(In reply to Telesto from comment #1)
> *** To page ***
>I read physical as: tangible, concrete; having to do with the material world
In this case, it might be true -- but not important to use the word "physical", which was loaned from Open Document Format for Office Applications (OpenDocument) Version 1.3 (20.418 text:anchor-type) [1].

More importantly:
> ... how I conceptualize it.
> 'To Page anchors the object to exact page where it inserted to. The image
> isn't linked to text flow/ The image doesn't follow the text flow. 
Thanks for daring to reveal how you think about it. This is the right direction -- to find a clear, short explanation that conveys the critical insight for "how to think about it (to page anchor)". Point about "text flow" seems important to include. 

So building on that...

here is a first attempt to elaborate "To page" anchor....

   "To page" anchors the object so that it always remains on current page, and the current page always remains in the document (with its current position in the sequence of pages). Objects with this anchor can be positioned in relation to the entire page or in relation to the page's text area. This position (and the page's position in the document) does not change as content and pages are added or removed from the document.


(my goal is to give a beginning user a good image of what is going on, using as plain, everyday language as possible, but also providing an expert user the critical information needed to understand the option -- have no need to include/defend any particular word or phrase by itself, so if my formulations have problems, then please offer alternatives!

Asking if @Mike (who has vast ask.libre experience with "to page") and @Regina have any opinions here -- so that the help page can be improved.

[1] https://docs.oasis-open.org/office/OpenDocument/v1.3/cs01/part3-schema/OpenDocument-v1.3-cs01-part3-schema.html#property-text_anchor-type
Comment 3 sdc.blanco 2022-05-26 12:00:57 UTC
Still in relation to [1]

"To character"

1.  "This command is only available for graphic objects."

afaict -- this sentence should be removed, because shapes, frames, formula, OLE objects can also be anchored "to character"

2.  Maybe add the following sentence to "To character"?

     Use the mouse to drag the anchor to the desired character.

[1] https://help.libreoffice.org/master/en-US/text/shared/01/05260000.html
Comment 4 Mike Kaganski 2022-05-26 12:26:12 UTC
(In reply to sdc.blanco from comment #3)
> 1.  "This command is only available for graphic objects."
> 
> afaict -- this sentence should be removed, because shapes, frames, formula,
> OLE objects can also be anchored "to character"

Agreed.

> 2.  Maybe add the following sentence to "To character"?
> 
>      Use the mouse to drag the anchor to the desired character.

I'd suggest to have a dedicated insertable block of the "how to define/change an anchor". Because if we use that text in several places, then a *possible* fix of bug 141161, bug 141162, bug 90933 would require to extend that text, and possibly in multiple places.
Comment 5 sdc.blanco 2022-05-26 13:26:52 UTC
(In reply to Mike Kaganski from comment #4)
> > 2.  Maybe add the following sentence to "To character"?
> > 
> >      Use the mouse to drag the anchor to the desired character.
This proposed text is for help page on the Anchor dropdown menu (e.g., right-click on selected object, Anchor)  (first URL in OP).
So purpose is only to give instructions on how to use "To Character".
 
> I'd suggest to have a dedicated insertable block of the "how to
> define/change an anchor".....
Perhaps a new "section" in this page:
https://help.libreoffice.org/master/en-US/text/swriter/guide/anchor_object.html

or -- it looks like the last paragraph on that page addresses "changing" an anchor. Maybe it should get an explicit heading.

"Moving an Anchor"

and probably the text in that paragraph needs some improvement (e.g., what does "keeping other object constraints in mind" mean?!)

I have no opinion about what should be changed, added, dropped in that last paragraph, so please make suggestions.

(and "noted" that this paragraph can get its own "section id" so that it can be embedded in other pages as needed).
Comment 6 sdc.blanco 2022-05-26 15:58:10 UTC
"As Character"  on "Anchor" page -- a first attempt. (-: 

Current: 

Anchors the selected item* as a character in the current text. If the height of the selected item is greater than the current font size, the height of the line containing the item is increased.

Proposed:

Anchors the selected object as a character in the current text. The height of the current line of text is extended, if the object is above (and/or below) the border for the highest character or object in the current line of text.


* in general on the "Anchor" page:  "item" -> "object"
Comment 7 sdc.blanco 2022-05-29 06:53:14 UTC
The help page refers to "Change Anchor", which is the Label, but it should be "Anchor", which is the "Context Label".  The following patch gives a better label (for the appearance in the Customize dialog) and adds a tooltip that will explain the meaning of "Anchor" icon in the toolbar.

https://gerrit.libreoffice.org/c/core/+/134791
Comment 8 Commit Notification 2022-05-30 06:02:24 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/help/commit/580f62a41db6366a3ab13bf16a96a643710605a3

tdf#149253  improve help about anchoring
Comment 9 Commit Notification 2022-05-31 00:22:16 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/core/commit/95b673946c0661391ad66eeae287f0922d96c6f8

tdf#149253 improve tooltip for Anchor icon

It will be available in 7.4.0.

The patch should be included in the daily builds available at
https://dev-builds.libreoffice.org/daily/ in the next 24-48 hours. More
information about daily builds can be found at:
https://wiki.documentfoundation.org/Testing_Daily_Builds

Affected users are encouraged to test the fix and report feedback.
Comment 10 sdc.blanco 2022-05-31 00:41:04 UTC
Have marked comments obsolete that were achieved in the patches in comment 8 and 9. These patches have mostly cleaned up the help pages by removing incorrect information, and integrating them better with each other, by adding related topics. 

No doubt further improvements are possible and worthwhile => leaving this ticket open, and unassigning myself.
Comment 11 Roger Stone 2022-07-11 10:07:55 UTC
Thanks for the patches, I hope to be able to apply them soon.
Comment 12 Olivier Hallot 2022-09-02 16:02:27 UTC
*** Bug 132864 has been marked as a duplicate of this bug. ***