Bug 457739

Summary: Okular handbook confused on annotations
Product: [Applications] okular Reporter: skierpage <skierpage>
Component: generalAssignee: Okular developers <okular-devel>
Status: RESOLVED FIXED    
Severity: normal CC: aacid, nate, p.r.worrall
Priority: NOR    
Version: 22.04.1   
Target Milestone: ---   
Platform: Fedora RPMs   
OS: Linux   
Latest Commit: https://invent.kde.org/graphics/okular/commit/0136eddb12151530bd162fd9b8862926a55007e3 Version Fixed In:
Sentry Crash Report:

Description skierpage 2022-08-10 22:15:17 UTC 
SUMMARY
I tried to remove a text annotation I made, and couldn't (because I wasn't in Browse mode). I read the "Annotations" section of the Okular handbook (Help > Okular Handbook and at https://docs.kde.org/trunk5/en/okular/okular/annotations.html ), and it has misleading Notes that indicate annotations don't work e.g. "document does not allow removing annotations".

STEPS TO REPRODUCE
1. Open a document with text annotations.
2. Switch to some Tool/mouse mode other than Browse such as Tools > Text Selection or annotation > Typewriter.
3. Try to delete a text annotation.
4. Read the Okular Handbook.

OBSERVED RESULT
The Annotations chapter's introduction says
    Note
    Due to DRM limitations (typically with PDF documents), adding, editing some properties or removing annotations could not be possible. 

"Removing Annotations" says
    Note
    This option could not be enabled because the document does not allow removing annotations.

But in fact you can remove annotations fine so long as you are in Tools > Browse mode.

EXPECTED RESULT
Clearer documentation. The annotation chapter should either prominently say you need to be using the Browse tool/mode to edit, adjust properties of, or remove annotations, or add this step to all instructions to click; and it should explain the limitations of DRM documents better. I don't know the preferred terminology (Browse mode? Browse tool?) and this is incomplete, but the following changes would improve the handbook:

In the Tools Menu chapter, change the section on Browse from:
	The mouse will have its normal behavior, &LMB; for dragging the document and following links and &RMB; for adding bookmarks and fit to width.
to something like:
	The mouse will have its normal behavior: &LMB; for dragging the document, following links, and selecting annotations; and &RMB; for adding bookmarks, fit to width, and opening a context menu for annotations.</para>

In the Annotations chapter, change to:
    Note
    It may not be possible to add, edit, or remove annotations in some documents (typically PDF documents) due to DRM limitations.
...
    To edit an annotation, switch to the Browse tool (<menuchoice><guimenu>Tools</guimenu> <guimenuitem>Browse</guimenuitem></menuchoice>), then click on it with the right mouse button and select Properties
...
    To remove an annotation, switch to the Browse tool (<menuchoice><guimenu>Tools</guimenu> <guimenuitem>Browse</guimenuitem></menuchoice>). Then either click on it with the &RMB;, ...

Remove the note "This option could not be enabled because..." altogether.

SOFTWARE/OS VERSIONS

Linux/KDE Plasma:
KDE Plasma Version:5.25.4
KDE Frameworks Version: 5.96.0
Qt Version: 5.15 on Wayland
Comment 1 Albert Astals Cid 2022-08-10 22:59:17 UTC 
No, that sentence can not be removed, but there's defenitely a wording issue.

Would you understand it better if it said

"
 This option may be disabled if the current document does not allow removing annotations. 
"

?
Comment 2 Paul Worrall 2022-08-25 09:11:00 UTC 
I think the point is:  it doesn't explain that for documents where removing annotations isn't prevented, you need to select the "Browse" tool to be able to select and delete annotations.  I was caught out by that too.
Comment 3 Albert Astals Cid 2022-08-26 16:54:00 UTC 
Do you expect to be able to remove annotations in "text selection" mode? 

There's nothing that is "text selection" about removing annotations
Comment 4 Paul Worrall 2022-08-27 07:02:32 UTC 
No.  A use case is:
1. Select an annotation tool and use it to add an annotation (e.g. an inline note)
2. Realise you've made a mistake and want to delete the annotation
3. Can't select the annotation to delete it because the annotation tool is still active
4. Check the help file.  It seems to say you can't delete annotations, it does not say "first select the Browse tool to allow selection of annotations"
Comment 5 Albert Astals Cid 2022-08-31 21:15:13 UTC 
Well, since my suggestions seem so bad, you're welcome to suggest the perfect text, this is Free Software after all, everyone can contribute.
Comment 6 Bug Janitor Service 2022-09-15 14:26:51 UTC 
A possibly relevant merge request was started @ https://invent.kde.org/graphics/okular/-/merge_requests/657
Comment 7 Oliver Sander 2022-12-01 15:29:44 UTC 
Git commit 0136eddb12151530bd162fd9b8862926a55007e3 by Oliver Sander, on behalf of Paul Worrall.
Committed on 01/12/2022 at 15:29.
Pushed by sander into branch 'master'.

Handbook: Select Browse to edit/delete annotations

Minor change to handbook to say that the Browse tool has to be selected before you can edit or delete annotations

M  +2    -2    doc/index.docbook

https://invent.kde.org/graphics/okular/commit/0136eddb12151530bd162fd9b8862926a55007e3