In the Position and Size tab (for Shape) and Type tab (for Image), the Vertical option (under Position) has the choices: "Top, Bottom, Below, Center, From top, From bottom" None are mentioned in [1] and [2] in the "Position > Vertical" section. Maybe some explanations should be given, especially differences between: Bottom vs. Below From bottom vs. bottom From top vs. Top [1] https://help.libreoffice.org/7.4/en-US/text/shared/01/05230100.html?System=WIN&DbPAR=WRITER [2] https://help.libreoffice.org/7.4/en-US/text/swriter/01/05060100.html?&DbPAR=SHARED&System=WIN
I agree, so marking this as NEW.. hopefully not to presumptuous
Created attachment 180137 [details] Draft help page for "Vertical" and "by" in Position section Please see attached, which shows the "current" help page (in upper left corner) and "proposed" revision (in lower right corner). Critical evaluations welcome. Especially appreciated from those who do not usually read help. (-: While the bug summary is not directly addressed, the idea is to give adequate information to be able to work out to what these options refer. (One caveat. Possibly "Below" should not be listed in the "by" field. There is an inconsistency in the interface (now filed as bug 149107) which has to be clarified before I can make a final version.
@Regina -- will be grateful for your critical evaluation of my attempt (in attachment 180137 [details]) to improve the help descriptions for "Vertical" and "by" (in relation to Vertical).
Created attachment 180140 [details] alternative proposal I have put some ideas and comments into the attached document. One problem in your proposal is, that parts are not styled consistent. A description talks about section labels, field labels and field values. There should exist a general guide line how to write and format these three parts. You might use formatting and/or single and double quotes, but it needs to be consistent throughout the help. Perhaps something to discuss on the mailing list or with Olivier. The fact that the 'by' field is enabled for the 'Vertical' value 'Below' looks like a bug for me. I have put the conditions into two lines, both starting with the label, because I think it is clearer. I have added the direction because it differs between 'From top' and 'From bottom'. The description needs to consider vertical writing modes.
(In reply to Regina Henschel from comment #4) Thanks for your comments. Iiuc, you have not identified any factual mistakes (which is good), and now that "Below" should not be part of "by", it is possible to make a cleaner version, which you did, and I am happy to work further with your version. About formatting: your idea sounds good. But best to file a ticket under Documentation, because all formatting would be expressed in help xml, where the current formatting possibilities are limited -- https://wiki.documentfoundation.org/Documentation/Understanding,_Authoring_and_Editing_Openoffice.org_Help/ About "Below": > 'by' field is enabled for the 'Vertical' value 'Below' looks like a bug for me. Me too. Based on: https://opengrok.libreoffice.org/xref/core/cui/source/tabpages/swpossizetabpage.cxx?r=05fa375f#327 > The description needs to consider vertical writing modes. Beyond my knowledge. But after the text settles down, I will ask Ming if he can help me. Thanks for the warning.
Adding the sentence in the description of "Vertical" about positioning relative to the region or reference point selected in the "to" control is the "resolution" to this bug. (short of writing a tutorial). The insight is that the meaning of the options in Vertical cannot be "understood" or "interpreted" by themselves. They must always be interpreted in relation to the "to" field. That is the point of the added sentence. The elaborations (and corrections) for the "by" control will show the "pattern" that "by" appears only for "From top" and "From bottom" -- which should help (a little) to differentiate from "Top" and "Bottom". Cannot see what more could be done in the context of the help page, but happy to receive comments. ------------- Slight, but necessary, correction to link about help formatting: https://wiki.documentfoundation.org/Documentation/Understanding,_Authoring_and_Editing_Openoffice.org_Help/3 Note <menuitem>, which is used for "bold" in the attached draft. That code is more or less the only possibility for formatting (along with a few specialized cases, <keycode>, <input>, <literal> <widget>).
Created attachment 180218 [details] Test of "from bottom" with "character" and "line of text" 3 issues demonstrated in attached file. Issue 1. Position of "Line of text" = meanline + top padding Question 1: correct? Issue 3. With "to character" and "From bottom" -- dialog would be sophisticated as follows: Vertical: From bottom by x cm to "Character top" (currently "Line of text") "Character bottom" (currently "Character") (as demonstrated in attachment. I believe these labels describe better) Notice that meaning of "Character" changes from "line reference" in "From bottom" context to "region reference" in Top/Center/Bottom context. Vertical: {Top, Center, Bottom} to Character (as demonstrated at bottom of attachment) Question 2. Is analysis correct? Question 3. Is it worth filing a new ticket to propose this label/dialog change? It may not be too difficult, need to (a) add these new labels and (b) change LB::RelChar|LB::VertLine to the new labels at: https://opengrok.libreoffice.org/xref/core/cui/source/tabpages/swpossizetabpage.cxx?r=05fa375f#330 (I have no strong opinion, but many Eve users expect/want the UI to be "intuitive" (i.e., so they do not have to read the help) -- and this change would be consistent with that ideal -- plus avoid a tricky confusion where "Character" means "line reference" in one context and "region" in another. Issue 2: (a little off-topic) Question 4: the pink box (at left side of attachment) cannot take a "by" value under 0,5cm -- why? a bug?
Created attachment 180222 [details] Table layout for "by" information Attached is "proof of concept" -- using "table" to layout the "by" options. (I accept that the layout could be improved, but I cannot get the width parameters accepted for the table cells). (have only shown table -- but final version will have "by" heading, introductory text, etc.). Questions: 1. I believe the information is accurate now. 2. Maybe the table form (even with "ugly" layout) is more usable/preferable than "sentence" form? (no strong opinion from me) 3. New issue: I believe that the reference line positioning depends on the entire line -- that is consider a line as follows: 12345 abcdefg If object is anchored "to character" at one of the numbers, but letters have a bigger padding than the numbers, then the vertical positioning will use the letters "character", even though the anchor is located in the numbers. (Is that right?) If so, then seems like something to mention in special box. (I think I have been tripped up by that "feature"? in the past).
(In reply to sdc.blanco from comment #7) > Created attachment 180218 [details] > Test of "from bottom" with "character" and "line of text" > > 3 issues demonstrated in attached file. > > Issue 1. Position of "Line of text" = meanline + top padding > > Question 1: correct? "meanline"? "Line of text" is the actual top edge of the line area. "As Character" anchored objects and all characters -inclusive their padding and border- are below this line. > > Issue 3. With "to character" and "From bottom" -- dialog would be > sophisticated as follows: > > Vertical: From bottom > by x cm > to "Character top" (currently "Line of text") > "Character bottom" (currently "Character") "Line of text" <> "character top", because 'as character' anchored objects influence "Line of text". "Line of text" is correct here. > > (as demonstrated in attachment. I believe these labels describe better) > > Notice that meaning of "Character" changes from "line reference" in "From > bottom" context to "region reference" in Top/Center/Bottom context. "Character bottom" is better than "Character" in context of "From bottom". That way it would be clear, that "Character bottom" is a reference line whereas "Character" is a reference area. > > Question 3. Is it worth filing a new ticket to propose this label/dialog > change? I would support a change from "Character" to "Character bottom" for the "From bottom" context. I do not support the proposed change for "Line of text".
(In reply to Regina Henschel from comment #9) > "meanline"? Highest point of lowercase case letters (without extenders or descenders), usually "x" is taken as prototypical But I withdraw that proposal. I understand now how I misinterpreted my tests. > "Line of text" is the actual top edge of the line area. How is line area defined? > "As Character" anchored objects and all characters -inclusive their padding > and border- are below this line. How is that different from top border of Character? In my tests with "to character" anchor, all of the Vertical options (Top/Center/Bottom/From bottom) are in relation to the top border of Character. What have I misunderstood?
(In reply to sdc.blanco from comment #10) > In my tests with "to character" anchor, all of the Vertical options > (Top/Center/Bottom/From bottom) are in relation to the top border of > Character. What have I misunderstood? A dynamic line area of 'single' line spacing might be vertically extended by an object which is anchored "as character" and is taller than the character content. Or a fixed line spacing which is larger than the character height results in a line area higher than the character height. Or the line spacing has a "leading" set. "Leading" is added on top of the dynamic height calculated from the line content. In those cases the difference between "top edge of line area" and "top border of character" is obvious. But I'm not sure whether the observed behavior is correct. For example, 'single' behaves different from 'proportional' with 99% or 101%, where I would expect that they are similar because 'single' should be the same as proportional 100%. Perhaps "From bottom to Line of text" is wrong for proportional line spacing or wrong for the others. Currently it is not consistent. I have used 'line area' with the idea of a paragraph content as stacked line areas. It is not an official term.
Created attachment 180271 [details] Tests to support my observations about "line of text" (In reply to Regina Henschel from comment #11) Still have questions. Not disagreements. Just clarifications. (attachment shows the test document I used to reach the following observations in relation to the configurations that you mentioned.) > A dynamic line area of 'single' line spacing might be vertically extended > by an object which is anchored "as character" and is taller than the > character content. I assume "character content" = point size. Anchored as character only offers vertical positioning (Top, Bottom, Center, From bottom) in relation to "baseline". If the "as character" shape is taller than the point size, then the "top border" of character gets increased to the top of the "as character" shape. Changing the position of the "as character" shape will change the vertical position of the text in relation to the "as character" shape, but (afaict) it is not possible to position the "as character" shape above the top border. with "to character" anchor in the same line as the "big" "as character" shape, and vertical positioning to "line of text" is always in relation to "top border" of "character" In this context, I understand "character" as the region defined by top/bottom borders, not the point size of the character. And I "detect" the top border by adding some colored lines in the Borders tab of the Character dialog. > Or a fixed line spacing which is larger than the character height > results in a line area higher than the character height. With this configuration, I learned how to get a shape to go above the top border! But -- as before -- line of text is the top border of character. > Or the line spacing has a "leading" set. "Leading" is added on > top of the dynamic height calculated from the line content. The first shape I put in this context was positioned at the top of the character border. And remained there when I added a big shape "as character", but after that, there was no consistency in how Vertical "From bottom" by 0cm to "Line of text" positioned the shapes. But -- at first -- the "top border of character" hypothesis continued to be supported. > But I'm not sure whether the observed behavior is correct. (-: Hence my questions. For the purposes of "help", the usual policy is to document the "expected" behavior (and not to mention bugs). (But sometimes it is better not to tell the expected behavior.) > Perhaps "From bottom to Line of text" is wrong for > proportional line spacing or wrong for the others. > Currently it is not consistent. The following comment from swpossizetabpage.cxx may be relevant here. // introduce mappings for new vertical alignment at top of line <LB::VertLine> // and correct mapping for vertical alignment at character for position // <FROM_BOTTOM> // Note: because of these adjustments the map becomes ambiguous in its values <eStrId>/<eMirrorStrId> and <nAlign>. These ambiguities are considered // in the methods <SwFrmPage::FillRelLB(..)>, SwFrmPage::GetAlignment(..)> // and <SwFrmPage::FillPosLB(..)> https://opengrok.libreoffice.org/xref/core/cui/source/tabpages/swpossizetabpage.cxx?r=05fa375f#319 > I have used 'line area' with the idea of a paragraph content as stacked > line areas. It is not an official term. Ok. But "From bottom" seems to be based around "character". While "line area" might help you to think about paragraphs, it may not be the appropriate conception in relation to "Line of text". I raised the idea of Character top / Character bottom in comment 7, mostly because it would make it easier to explain in the help. But that question/issue does not have to be resolved for this ticket to be resolved. This ticket is focused on improving the documentation. Maybe the attached proposal -- with the table -- is "good enough" (in the sense of explaining the "by" control, and which options are available in relation to that control, and what actions/decisions have to be made. If that is true, then I will go forward and finish that patch -- but I still have question #3 in comment 8.
Created attachment 180288 [details] Test for from bottom by 0mm to Line of Text The first page shows the behavior for line spacing "fixed" and "leading". Notice that the reference line for 'Line of Text' is not the top of the character area. The second page shows the difference between line spacing "single" and "proportional" for cases, where the actual line height is larger as the default, which is created from default font size. (In reply to sdc.blanco from comment #12) > > A dynamic line area of 'single' line spacing might be vertically extended > > by an object which is anchored "as character" and is taller than the > > character content. > I assume "character content" = point size. Yes. The area between blue top and bottom border in my attachment. > Anchored as character only offers vertical positioning (Top, Bottom, Center, > From bottom) in relation to "baseline". Top, Bottom and Center offer relation to "Character" and "Row" in addition. In my attachment I have used "Center to Character". > > If the "as character" shape is taller than the point size, then the "top > border" of character gets increased to the top of the "as character" shape. I cannot confirm that. The blue top and bottom border of the characters are not affected in my attachment. > with "to character" anchor in the same line as the "big" "as character" > shape, and vertical positioning to "line of text" is always in relation to > "top border" of "character" Look at the second page. Whether "Line of Text" is the top edge of the extended line height or the top edge of the default character size depends on the kind of line spacing. > I raised the idea of Character top / Character bottom in comment 7, mostly > because it would make it easier to explain in the help. But that > question/issue does not have to be resolved for this ticket to be resolved. Your proposed text does not specify where the reference line exactly is. So it would fit in any case. I agree, that could solve to give information about "by". The inconsistency between the position of "Line of Text" in case of proportional line spacing and other line spacing kinds needs to be addressed in a separate bug report. (In reply to sdc.blanco from comment #8) > 3. New issue: I believe that the reference line positioning depends on the > entire line Yes, not the anchor character is relevant but the entire line.
(In reply to Regina Henschel from comment #13) (many thanks for your test document. I understand better now about "Line of text", but still many mysterious aspects in my experiments with "line reference points", especially character and row.) -- I guess interactions between size and/or type of line spacing, character padding, and object size -- where I have not found stable general principles -- and do not know when I am encountering bugs). But returning only to the issues relevant to this ticket: > Your proposed text does not specify where the reference line exactly is. So > it would fit in any case. I agree, that could solve to give information > about "by". Thanks. As you know, the rest of the help page (where this fragment would appear) specifies the meaning of the individual reference lines ("Line of text" , "Character", etc. (though I think the current entry for "Line of text" needs to be improved). > > 3. New issue: I believe that the reference line positioning depends on the > > entire line > Yes, not the anchor character is relevant but the entire line. Thanks for this confirmation, which supports my belief that the current text on the help page is incorrect. ----------------------- As character Anchors the selection as character. The height of the current line is resized to match the height of the selection. ----------------------------- As I understand, this is only true if (a) the object is actually bigger than the current line height, and (b) if there is not another object in the same line that is even higher, and (c) fixed spacing is not being used. I will work further on developing the help text -- and also see if I can get a more stable description of "Line of text" (I accept that line of text is not the same as top border of character, but not how to explain how to identify where the line will be for a given line of text. My current hypothesis is the "line of text" is the top edge of the selecting highlighting that is shown when selecting a few characters in a line.)
Created attachment 180298 [details] Possible final draft of help for Vertical and by The attachment shows the full revised proposal. I believe it is ready to be submitted -- but of course will be good with critical evaluation. Significant points. 1. Have changed "reference point" to "reference line". For all vertical positioning, it is the "line" that is important, not a particular point. 2. Have simplified the "by" table significantly. I believe it is all correct now (have checked, tested the variations) - but it is tricky material, so will be glad for close attention. Comment 6 explains why this attachment can be considered a resolution of this bug.
Your "final" version of the text looks good to me. For other problems with reference line "Line of Text" I have created bug 149234 and bug 149235.
Seth Chaiklin committed a patch related to this issue. It has been pushed to "master": https://git.libreoffice.org/help/commit/a6112298c946828a9d93b52384972f5e5f6c0538 tdf#148486 clarify "Vertical" and "by" controls in Position and Size
Closing this ticket as "FIXED" because reasons in comment 6 are now achieved. Note that the "published" version has an "improved" table layout for "by" and a few other simplifications compared to attachment 180298 [details]. Followups should get a new ticket.