Download it now!
Bug 52069 - LibreOffice help gives insufficient information about how to update cross-references
Summary: LibreOffice help gives insufficient information about how to update cross-ref...
Status: RESOLVED FIXED
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Documentation (show other bugs)
Version:
(earliest affected)
3.5.5.3 release
Hardware: Other All
: medium normal
Assignee: Not Assigned
URL:
Whiteboard: target:3.7.0
Keywords:
Depends on:
Blocks:
 
Reported: 2012-07-13 19:10 UTC by Lou
Modified: 2012-07-25 07:13 UTC (History)
2 users (show)

See Also:
Crash report or crash signature:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Lou 2012-07-13 19:10:23 UTC
Need documentation on how to update cross-references.

This is big issue; a main reason for going to LibreOffice is weaknesses in Pages and iWorks, such as no cross-referencing,



While I'm at it, documentation on math formula module is very poor. Screen shots do not match what's actually visible. No mention of how to get to Elements, etc.

We gotta spell stuff like this out! If you like I can make up flow sheet for general equations.
Comment 1 Roman Eisele 2012-07-14 09:10:05 UTC
> Need documentation on how to update cross-references.
> 
> This is big issue; a main reason for going to LibreOffice is weaknesses in
> Pages and iWorks, such as no cross-referencing,

Thank you very much for your bug report!

Well, it is a bit difficult to understand what's going on. We would highly appreciate it if you could give us more details when you report a problem with LibreOffice (especially, which version of LibreOffice you use; which user interface language; and it would be also useful to know the MacOS version you use, the MacOS user interface language; all this can be necessary to know, especially when we have to investigate in function keys and shortcuts, which often depend on versions and user interface language).

But assuming that you use LibreOffice 3.5.5 (or so), I have tried to reproduce the problem, and can partially reproduce it. I am using LibreOffice 3.5.5.3 on MacOS X 10.6.8 (Intel), both with German interface, but have switched to US English for this test, on a MacBook Pro (2010).

I can confirm that pressing F9 does NOT update cross references for me. However, I have the impression that this is not a bug in LibreOffice, but a general problem with function keys on newer MacOS X versions: if I remember correctly, there are also other applications which don't react as expected to pressing F keys. The reason behind this behaviour is that MacOS X now handles the F keys itself instead of passing the F key to the current application (as it was the case in earlier versions of MacOS (7, 8, 9) and MacOS X (10.1 to 10.4, if I remember correctly)).

For me, the solution is not to press just F9, but fn + F9; the fn key is the special "function" key at the bottom left of my MacBook keyboard. However, I don't know what to do on keyboards without an fn key; this is a question we (you) should ask Apple or some Apple expert ;-)

@Lou:
-> Can you please state if this solves the issue for you, too? Just add a comment to this bug report.


Alternatively, you can always (!) update cross-references via the menu bar: select the "Tools" menu, then select "Update", and then, from the sub-menu which appears right beside "Update", select "Fields" (or "Update All"). This should work regardless of operating system, UI language, keyboard settings, etc.

But you are definitely right that this information is missing from the LibreOffice help! At least for me (LibreOffice 3.5.5.3), the Help just says:

  "Updating Cross-References
  
  To manually update the cross-references in a document, press F9."

And this is a bit stupid, given the fact that:
(a) selecting the command from the menu is IMHO the primary way to select any command; keyboard shortcuts and F keys are only *alternative* ways to select commands and are directed especially at power users;
(b) keyboard shortcuts and F keys may not always work, depending on user interface language, keyboard type and settings.

-> THIS is a documentation problem, of course, which needs to be fixed!


> While I'm at it, documentation on math formula module is very poor. Screen
> shots do not match what's actually visible. No mention of how to get to
> Elements, etc.

This is a good hint, thank you! But could you please file a separte bug report for this? I am sorry, but it makes live much easier for us (we are only volunteers and not paid in any way!) and prevents misunderstandings and loss of track when we get only one issue per bug report.

> If you like I can make up flow sheet for general equations.

This is a nice idea, thank you very much for your friendly proposal! It would be best if you could sent a short e-mail about this proposal (and about the shortcomings of math formula module documentation, if you want) to
  David Nelson <commerce@traduction.biz> or
  Sophie Gautier <gautier.sophie@gmail.com>
which are our friendly documentation experts. They can tell you best how your flow sheet and other stuff could get added to documentation.
Comment 2 Lou 2012-07-14 14:45:07 UTC
Thank you, Roman, for quick response.  As soon as I can, I'll be more 
complete and precise, and I'll isolate each issue as you suggest.
By the way, I'm delighted that a person actually responds!!! (Try that 
with Microsoft or Apple!)
Lou Jagerman
Comment 3 Lou 2012-07-14 17:01:54 UTC
Background: LibreOffice 3.5.5.3.  iMAC 216Ghz Intel Core 2 Duo, 2.5 Gig 
RAM, OSX 10.6.8, Apple keyboard, which has no fn key. English.

I write science/math books (Google or Amazon: "Louis Jagerman 
relativity") with hundreds of page-sensitive cross-references.
Copied part of new book I'm writing with several cross-refs, saved as 
.odt. Moved targets (bookmarks) and their linked cross-refs around to 
new pages.

In this case, F9 just reveals all open windows - nice OSX feature - I'd 
rather leave that alone. _*Still, in my setup, F9 does not update links, 
despite what documentation says.*_
Yes, tried just F9 alone, and together with Control, Option, Apple, etc. 
keys.  Apple+F9 just shows bookmark.
Though it's more keystrokes and not quite as intuitive (? "fields"), 
_*Tools...Update...All or Fields does work*_.

In my opinion, (1) users should find correct accurate documentation, 
including in "help" under "cross-referencing." And (2) if user wants to 
devise keyboard shortcut, can that be done? (3) A nice touch would be an 
"update" option under "Cross-reference."  (4) If you read my books 
you'll see I like to provide readers with very specific instructions.  
Documentation should have a numbered protocol for typical 
cross-reference, using common terminology such as "target."  Here 
WordPerfect was outstanding, and you may wish to see how Corel laid it 
out.  Yes, a cross-ref involves a "field." but that's ancient and 
confusing terminology.

If I must, I will use your Tools...Update method.

Thank again, Roman.  (.de I see. Ich war in Berlin geboren.)
Comment 4 Roman Eisele 2012-07-15 16:44:41 UTC
@Lou:
Thank you very much for your background information!

I think that we should split this issue.

(a) The F-key issue:
That F9 does not work is IMHO a MacOS X issue, I mean, the problem is that MacOS X "caches" the F9 event and interprets it as "reveal all open windows" -- therefore, LibreOffice does not receive the F9 key event at all, and therefore can't handle it. It should be possible to change this behaviour in the MacOS X System Preferences, but don't ask me how exactly -- Apple has changed the handling of F-keys and keyboards several times in the last updates of MacOS X, and I did not catch up with these changes :-( But some MacOS X support expert should be able to tell us what to do.

(b) The documentation issue (your point (1)):
As I already wrote in comment #1, you are definitely right that the LibreOffice help for this action is incomplete and inappropriate! *This* should get fixed soon.

(c) Changing the shortcut (your point (2)):
> And (2) if user wants to devise keyboard shortcut, can that be done?
Yes, I think so ;-) Open any Writer document. Then select from the menu bar "Tools > Customize ...". In the dialog window which appears, entitled "Customize", select the 2nd tab ("Keyboard"). At the top right, check "Writer" (instead of "LibreOffice"). In the list "Shortcut keys", search for "F9", next to which you should find "Fields", and click on the button "Delete" at the right -- because F9 does not work anyway, we can remove this key. Then, in the list "Category" at the bottom left, select "Edit"; then, in the list "Function" at the bottom, select the first entry called "Field" (I see "Field" two times, don't ask me why!). Now select in the list "Shortcut keys" at the top any free entry you want to use; I used Cmd+Y to test. Now click on the button "Modify" at the right. You should now see the Command "Field" associated to the keyboard shortcut you selected (again in the list "Shortcut keys"). Click "OK". At least for me, Cmd+Y correctly updates all fields now, including the cross-references.

(d) Improvements to UI (your point (3)):
> A nice touch would be an "update" option under "Cross-reference."
A good idea; please file a separate bug report for this, and set the "Importance" field in this report to "enhancement", to make clear that this is an enhancement request.

(e) Improvements to terminology (your point (4)):
I agree with you that "Fields" is an example of strange terminology, however, I'm not in the position to decide this. The best thing to do would be to
Comment 5 Roman Eisele 2012-07-15 16:46:51 UTC
[continued from comment #4]
... file yet another bug report for this, and to set the "Importance" field in this report to "enhancement", to make clear that this is an enhancement request.

Again, thank you for your input and considerations!
Comment 6 Roman Eisele 2012-07-15 17:02:59 UTC
In this bug report, we will concentrate on point (b) from my distinction in comment #4, i.e. on the documentation issue. To put it all together:


LibreOffice Help says ("Help > LibreOffice Help > Index > cross-references > inserting and updating"):

  "Updating Cross-References

  To manually update the cross-references in a document, press F9."

No information is given about how to select this command from the menu. This is irritating, because:
(a) selecting the command from the menu is IMHO the primary way to select
    any command; keyboard shortcuts and F-keys are rather *alternative* ways
    to select commands and are directed especially at power users;
(b) keyboard shortcuts and F-keys may not always work, depending on
    user interface language, keyboard type and settings.

Therefore, I propose to change this part of the LibreOffice help to:

  "Updating Cross-References

  To manually update the cross-references in a document, choose
  "Tools - Update - Fields" from the menu or press F9."


Regarding the documentation, this is a valid bug report, therefore I change the Status to "NEW" (confirmed). Setting Version according to comment #3. Setting Platform to "All".


@András Timar:

Hello András,
I insert your address into the CC list because I think you are our expert for "fixing bugs in localhelp". This is a valid report about a lack or shortcoming of our LibreOffice help, so please fix this or tell me whom I should contact for fixing this. I have already proposed an improved formulation above. Thank you very much in advance!
Comment 7 Roman Eisele 2012-07-15 17:04:46 UTC
I forgot to update the summary, sorry.
Comment 8 Not Assigned 2012-07-16 15:53:56 UTC
Andras Timar committed a patch related to this issue.
It has been pushed to "master":

http://cgit.freedesktop.org/libreoffice/help/commit/?id=d2e2492baeea715a2a8466964cf00e4be50af885

fdo#52069 updating cross-references help
Comment 9 Lou 2012-07-17 01:23:44 UTC
Roman, you're right, Apple's changed how to reassign F keys, and I could 
not figure it out. And even if I could, I wouldn't know how to make 
LibreOffice obey and update.
Lou
Comment 10 Roman Eisele 2012-07-17 06:13:27 UTC
(In reply to comment #8)
> Andras Timar committed a patch related to this issue.

@ Andras:
Thank you very much, Andras, for fixing this so fast!
Comment 11 Roman Eisele 2012-07-25 07:13:30 UTC
Marking this as fixed.


@ Andras:
Can you backport this to the 3.6.x branch (not for 3.6.0, but e.g. for 3.6.1)? So users would benefit from your change 6 months earlier ;-)