GNOME Bugzilla – Bug 707383
Add instruction to remove pictures directly on eog
Last modified: 2020-11-09 21:45:37 UTC
Created attachment 253971 [details] [review] A mallard page instructing to remove pictures Eog offers the functions to remove pictures viewing them. One of the two way is to move them to the trash, the other to delete them permanently. Eog documents should have an instruction about that. I've written a mallard page on that. Could you please review it?
Hi! I can confirm there is no complete user help on ways you can delete a a picture. Marking bug as NEW. Also, it would be great if you can attach the patch rather than the *.page file. We can use the patch and apply on to our local git repository of eog and test it using yelp. Thanks.
Created attachment 254029 [details] [review] help: Add instruction to remove pictures This is a patch for the users manual.
Created attachment 254030 [details] [review] help: Add new remove.page to HELP_FILES This is a patch for Makefile.am.
Hi Sindhu, (In reply to comment #1) > I can confirm there is no complete user help on ways you can delete a a > picture. Marking bug as NEW. > > Also, it would be great if you can attach the patch rather than the *.page > file. We can use the patch and apply on to our local git repository of eog and > test it using yelp. Thank you for the comment. I've attached patches.
Review of attachment 254029 [details] [review]: Some general comments: In the introductory paragraph, try to include how it would be useful to the user to accomplish the tasks mentioned on the page, that is in which scenario would he find the features listed on the page useful. The link to the page which shows how to restore files once deleted, needs to be rearranged. I would say something along the lines of: "You can delete pictures from <app>eog</app>." followed by the steps and then the <note style="tip">To restore deleted pictures from trash, consult the Desktop user help for <link xref=???>Recover a file from the Trash</link>. </note>" and here linking to the appropriate page. I am using the word "pictures" and not "images" primarily because of my personal bias, however should the word "images" or "files" be appropriate (since eog can also display .gif I think?), then please use the appropriate terminology. In the second section "Delete pictures permanently": 1. Can bypass be replaced with a more common word? 2. "Note that..." should be added as a <note style="warning"><p>Files deleted permanently cannot be recovered.</p></note>. You have a typo in the first step. Not "yor", "you". I would reword the sentence this way: "Open the picture you wish to delete." "Select Edit > Delete Image". No need to say "on the menu bar" as the tag <keyseq> indicates that the options are available in the menu bar. Please keep the steps atomic. I would reword it this way: Step 3: "A confirmation dialog will appear asking whether you wish to confirm the deletion". Press ? to confirm the deletion. About the tip towards the end...what do you mean by "same way"? Please be specific.
Created attachment 254177 [details] [review] help: Add instruction to remove pictures I updated the page following the review comment.
Hi Sindhu, Thank you for the review. I updated the page. (In reply to comment #5) > Review of attachment 254029 [details] [review]: > > Some general comments: In the introductory paragraph, try to include how it > would be useful to the user to accomplish the tasks mentioned on the page, that > is in which scenario would he find the features listed on the page useful. > All right. How about this: "If you find unnecesary or unwanted pictures while using the <app>Image Viewer</app>, you can remove them immediately without having to open the file manager." > The link to the page which shows how to restore files once deleted, needs to be > rearranged. I would say something along the lines of: "You can delete pictures > from <app>eog</app>." followed by the steps and then the <note style="tip">To > restore deleted pictures from trash, consult the Desktop user help for <link > xref=???>Recover a file from the Trash</link>. </note>" and here linking to the > appropriate page. > Thank you for the suggestion. I rewrote as you said. I am not using "delete" in the sense of moving files to the trash with consistency. > I am using the word "pictures" and not "images" primarily because of my > personal bias, however should the word "images" or "files" be appropriate > (since eog can also display .gif I think?), then please use the appropriate > terminology. > I am using "pictures" with purpose, althoug we could use "images". I follow the terminology of the other pages, which use "picture". > In the second section "Delete pictures permanently": > > 1. Can bypass be replaced with a more common word? I rewrote it: "You can delete pictures permanently without moving them to the trash." > 2. "Note that..." should be added as a <note style="warning"><p>Files deleted > permanently cannot be recovered.</p></note>. > > You have a typo in the first step. Not "yor", "you". I would reword the > sentence this way: "Open the picture you wish to delete." > Good catch, thanks. > "Select Edit > Delete Image". No need to say "on the menu bar" as the tag > <keyseq> indicates that the options are available in the menu bar. > Deleted it. > Please keep the steps atomic. I would reword it this way: > Step 3: "A confirmation dialog will appear asking whether you wish to confirm > the deletion". Press ? to confirm the deletion. > Hmm, actually, I tried to start each step with a verb in the imperative form. That respects the documentation style guide [1]. On the other hand, I understand your point too. Fow now, I rewrote it as you said. But it might be better to follow the style guide. Could you check which is better? > About the tip towards the end...what do you mean by "same way"? Please be > specific. How about this: "and then remove or delete them following the above instructions." [1] https://developer.gnome.org/gdp-style-guide/stable/infodesign-12.html.en#infodesign-15
Hi! Thank you for your patch. > All right. How about this: > "If you find unnecesary or unwanted pictures while using the <app>Image > Viewer</app>, you can remove them immediately without having to open the file > manager." > I rewrote it: > "You can delete pictures permanently without moving them to the trash." > How about this: > "and then remove or delete them following the above instructions." There is no need to put in reworded sentences *here* as reply to my comments. Incorporate them in the next iteration of your patch. Long comments are hard for me to skim and scan, hence the request. > Thank you for the suggestion. I rewrote as you said. > I am not using "delete" in the sense of moving files to the trash with > consistency. OK. I will take a look at next iteration and give my comments. > I am using "pictures" with purpose, althoug we could use "images". I follow the > terminology of the other pages, which use "picture". If it's the right thing to use then I have no problem. I mentioned so because I was unsure myself :) We should confirm it from someone from the docs team. > Hmm, actually, I tried to start each step with a verb in the imperative form. > That respects the documentation style guide [1]. On the other hand, I > understand your point too. Fow now, I rewrote it as you said. But it might be > better to follow the style guide. Could you check which is better? I've been told the style guide is outdated though nobody confirms me what parts of it should I ignore so I always avoid looking into it until the very end of the iterations of the patch. We can definitely consult someone from the docs team to help us out for this.
Review of attachment 254177 [details] [review]: "If you find unnecesary or unwanted pictures while using the Image Viewer, you can remove them immediately without having to open the file manager. There are two ways to remove pictures. One of them is to move them to the trash. The other is to delete them permanently." Can we reword it to the likes of "You can remove pictures you don't need using <app>Image Viewer</app>. You can remove pictures by either moving them to Trash or deleting them from your computer." "Move pictures to the trash" Trash with a capital T, please. "You can remove pictures from the Image Viewer." This is not required as the section title is quite specific in itself and possibly needs no explanation preceding our introduction on the page. "Open the picture that you want to remove." "<link xhref="open">Open a picture</link> that you wish to remove." "Choose Edit ▸ Move to Trash." "Select" and not "Choose". "Alternatively, right-click on the picture to open the context menu, and then choose Move to Trash." We should try to keep user help system agnostic. For example, touch screen devices running GNOME don't have right click. During my internship, I made a few notes from the regular reviews given by my mentor, I look through it when I submit my documentation patches, perhaps this http://sindhus.bitbucket.org/suggested-workflow-for-writing-help.html could be useful to you too? :) "To restore removed pictures from the trash, consult the GNOME Help for Recover a file from the Trash. Can we reword it to "To restore pictures you have moved to Trash, consult GNOME help to Recover a file from the Trash"? "Delete pictures permanently" "You can delete pictures permanently without moving them to the trash." This line isn't quite necessary as again the section heading is quite self-explanatory. "Note that the files deleted in this way cannot be restored." No need to say "Note..." as the warning symbol indicates that this text is of importance due to the consequences of the preceding user help instructions. Why have we used "files" instead of pictures here? "Open the picture that you want to delete." "<link xhref="open">Open a picture</link> that you wish to remove." "Choose Edit ▸ Delete Image." Again, "Select" instead of "Choose", please. "Alternatively, you can use Shift+Delte shortcut keys." 1. "Delte" is a typo. You might want to enable spell-check in your text editor :-) 2. No need to mention "shortcut keys" as the styling of the XML tag <keyseq> indicates that those are keys to be pressed. 3. "press" and not "use". "A confirmation dialog will appear asking whether you want to confirm the deletion. Press the Delete button in the dialog to confirm the deletion." I see a "Move to trash" button here. I have compiled eog from git master at the time of writing this review. Could we reword to this to the likes of "A dialog will appear to confirm your choice of action for this picture. To confirm your deletion, select <gui style="button">Move to Trash</gui>." "If you do not want the confirmation dialog any more, select the Do not ask again during this session option in the dialog." You can put this text after the <steps> tag. as it does not directly help accomplish the task. It's auxiliary (that is to say, it helps the main steps). I would tweak the sentence to read "If you wish to delete pictures without confirming your deletion for each picture, select Do not ask again during this session." "You can remove multiple pictures in the image gallery at once. Select pictures that you want to remove in the gallery, and then remove or delete them following the above instructions." I think this deserves a section of it's own possibly titled "Delete multiple pictures at once"?
Created attachment 254647 [details] [review] help: Add instruction to remove pictures Revised the patch.
Thank you for the comments. I've revised the page. (In reply to comment #9) > Review of attachment 254177 [details] [review]: (snip) > "Choose Edit ▸ Move to Trash." > > "Select" and not "Choose". > Modified. But, could you tell me why "select" is more appropriate than "choose"? > "Alternatively, right-click on the picture to open the context menu, and then > choose Move to Trash." > We should try to keep user help system agnostic. For example, touch screen > devices running GNOME don't have right click. During my internship, I made a > few notes from the regular reviews given by my mentor, I look through it when I > submit my documentation patches, perhaps this > http://sindhus.bitbucket.org/suggested-workflow-for-writing-help.html could be > useful to you too? :) > Yes. Thank you for the detailed check list. I deleted the sentence because it is unnecessary. (snip) > "Note that the files deleted in this way cannot be restored." > No need to say "Note..." as the warning symbol indicates that this text is of > importance due to the consequences of the preceding user help instructions. Why Deleted the phrase as you said. In General, however, we should not expect that every reader will see annotation symbols. For example, users who read documents with Orca, the GNOME screen reader, may not realize that is a warning note. Of cource, eog users do not probably use a screen reader. (snip) > "A confirmation dialog will appear asking whether you want to confirm the > deletion. Press the Delete button in the dialog to confirm the deletion." > > I see a "Move to trash" button here. I have compiled eog from git master at the > time of writing this review. > That's weird. Can you check the version of your eog is 3.9+? Here is a screenshot of the dialog of eog 3.9.92 https://cloud.gnome.org/public.php?service=files&t=f3b9fa26b7c168f3e328752fd013bd40 I used the following version: $ jhbuild run eog --version GNOME Image Viewer 3.9.92 $ jhbuild info eog | grep Install Install version: c9ad55243211e5e9335a16102560f4561e9740e1 Install date: 2013-09-11 15:11:49 (snip) > "You can remove multiple pictures in the image gallery at once. Select pictures > that you want to remove in the gallery, and then remove or delete them > following the above instructions." > > I think this deserves a section of it's own possibly titled "Delete multiple > pictures at once"? Thank you for the suggesion. I'll write a page for that task after fininshing this page.
(In reply to comment #11) > Modified. But, could you tell me why "select" is more appropriate than > "choose"? That's how I learnt it. I cannot remember the *why* so I am CC-ing Kat from the documentation team to clarify for you. > Deleted the phrase as you said. In General, however, we should not expect that > every reader will see annotation symbols. For example, users who read documents > with Orca, the GNOME screen reader, may not realize that is a warning note. Of > cource, eog users do not probably use a screen reader. You clarified it yourself :) Still Kat should be able to comment why note element is important.
Created attachment 260023 [details] Move to Trash menu item screenshot > That's weird. Can you check the version of your eog is 3.9+? > Here is a screenshot of the dialog of eog 3.9.92 > https://cloud.gnome.org/public.php?service=files&t=f3b9fa26b7c168f3e328752fd013bd40 > I used the following version: > $ jhbuild run eog --version > GNOME Image Viewer 3.9.92 > $ jhbuild info eog | grep Install > Install version: c9ad55243211e5e9335a16102560f4561e9740e1 > Install date: 2013-09-11 15:11:49 Screenshot attached.
Created attachment 260024 [details] EOG version screenshot > I used the following version: > $ jhbuild run eog --version > GNOME Image Viewer 3.9.92 > $ jhbuild info eog | grep Install > Install version: c9ad55243211e5e9335a16102560f4561e9740e1 > Install date: 2013-09-11 15:11:49 > ➜ ~ jhbuild run eog --version GNOME Image Viewer 3.11.2 ➜ ~ jhbuild info eog | grep Install Install version: aae3be0031991749d60631080867c403a7fd7348 Install date: 2013-11-17 12:01:50
Hi Sindhu, I'm so sorry for my late reply, and thank you for checking that and your screenshots. Correct me if I'm wrong. In comment #9, you commented about "delete-permanently" section and said that you saw a "Move to trash" button in the delete-confirmation dialog. And you suggested me that the "Delete" button should be replaced with the "Move to trash" button, am I right? > "A confirmation dialog will appear asking whether you want to confirm the > deletion. Press the Delete button in the dialog to confirm the deletion." > > I see a "Move to trash" button here. I have compiled eog from git master at the > time of writing this review. But your screeenshots do not show that. If I misunderstand you, could you tell me what you meant by the above comment. And if you are saying the page gives a wrong information or wrong instructions, please tell me about the wrong parts. Thank you in advance.
Hi Jiro, Sindhu, is there anything left to do here? Can we push the current page?
This is covered in https://help.gnome.org/users/eog/stable/edit.html What is left to do here? Covering how to bypass the trash? Is that really needed?
Closing this bug report as no further information has been provided. Please feel free to reopen this bug report if you can provide the information that was asked for in a previous comment. Thanks!