Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added push-to-external application feature documentation #244

Merged
merged 8 commits into from
Nov 9, 2019
Merged

Added push-to-external application feature documentation #244

merged 8 commits into from
Nov 9, 2019

Conversation

michizhou
Copy link
Contributor

Added new documentation with details about usage of the push-to-external-application feature through the tools submenu and configuration of the feature that allows one to select which external application a user wishes to push to. Also modified heading to comply with markdown lint rules.

Closes #207

@koppor
Copy link
Member

koppor commented Oct 27, 2019

This is a good start. Please add screenshots.

If you are good in Java-coding, I would like to take the screenshots using a TestFX test. See https://github.com/TestFX/TestFX for details on TestFX. There should be some tests in our code.

@michizhou
Copy link
Contributor Author

@koppor I have added some screenshots I took of the JabRef application with the push-to-external application button and dropdown menu highlighted without using TestFX. If these are not sufficient, please let me know and I can try to take the screenshots using TestFX.

@koppor
Copy link
Member

koppor commented Oct 27, 2019

OK. - When reading the text, I do not see which tools are there. I remember that we have preferences where the user can configure paths etc. Is this still the case? Can you check (and provide a screenshot)?

I also found following FAQ. - Can you include the text here, too? Just the answer is enough.

Q: JabRef does not push to vim, although I have configured the right path and server name. What is going on?

A: You have to start vim with the option --servername (such as vim --servername MyVimServer). If you get the Unknown option argument message, it means your version of vim does not include the clientserver feature (you can check with vim --version). In such a case, you have to install another version of vim.

@michizhou
Copy link
Contributor Author

@koppor If you're talking about the Preferences window that is reminiscent of the following window below, then that window will pop up when you select Options -> Preferences in the top toolbar.
Preferences_Window
Preferences_Window
Should I include these screenshots in the documentation? Or did you have something else in mind?

@Siedlerchr
Copy link
Member

You can select the Push-App in the Preferences (External Programs) from the drop down/combobox
This then changes the icon-button in the toolbar.
See JabRef/jabref#5375 (comment)

I think it would be nice to illustrate it with screenshots, showing the effect and where the "Push"-Button is located.

@koppor
Copy link
Member

koppor commented Oct 29, 2019

Other screenshots: koppor/jabref#367. You can just save them and re-use them.

@koppor
Copy link
Member

koppor commented Oct 29, 2019

Please also add a screenshot of TeXStudio which shows that the entry is pasted. Do you have a minimal latex document (and a minimal bibliography)?

There should be two screenshots. One for \cite{entryOne} and one for \cite{entryOne,entryTwo} so that it is illustrated, that first the complete \cite is inserted, then the cite is extended.

@michizhou
Copy link
Contributor Author

@koppor I've added additional screenshots and expanded documentation for the push-to-external application feature section as a whole. Let me know if this will suffice.

@koppor
Copy link
Member

koppor commented Oct 31, 2019

Thank you for keeping working on this. Documentation writing is hard. Even for "small features"

May I ask which version you used? I remember using http://builds.jabref.org/master/. There, I did not see any drop-down menu. Did you?

Refs koppor/jabref#367 (where I posted screenshots)

@michizhou
Copy link
Contributor Author

@koppor Not a problem. It's my pleasure to work on this, as I am interested in its resolution and do think it has the potential to benefit many JabRef users.

As for the version of JabRef I used, my version is 4.3.1 (the latest stable release for MacOS), and I had downloaded it from Fosshub, not http://builds.jabref.org/master/. I'll download the dev build from there (version 5.0.0) and redo the screenshots if need be.

@michizhou
Copy link
Contributor Author

@koppor If you could look over my most recent changes to the push application documentatioon whenever you are able, I would greatly appreciate it. Thank you.

Copy link
Member

@koppor koppor left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for incorporating the comments. Two minor things remain.

On MacOS:
![Push to External MacOS](images/Push-External-Button-MacOS.png)

On Windows:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add two spaces ( ) after "On Windows:"? This leads to a hard line break. (Please also at "On Mac OS:")


When you click on the push-to-external application button, JabRef will export your selected entries to a file generated by the selected external viewer application. As an example, here is what happens when you export one entry to TexStudio.

![Initial Push to External Export](images/Initial-Push-Export.png)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for installing the tools. The thing is, that one should have a .tex file opened. You can use that file: https://github.com/latextemplates/scientific-thesis-template/blob/master/latexhints-english.tex#L43

Adding a cite command to a BibTeX file leads to compilation errors.

grafik

Copy link
Contributor Author

@michizhou michizhou Nov 6, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't quite understand what you want. When I export a bibliography in JabRef using push-to-external application, it gets all existing entries in the bibliography and I get the following:

After exporting first entry to TexStudio
Screen Shot 2019-11-06 at 5 11 21 PM

After exporting additional (second) entry to TexStudio
Screen Shot 2019-11-06 at 5 14 25 PM

Should I use these screenshots instead? Or are you saying that the exported file has to be in .tex format (which I then show screenshots for)? If it's the latter, I'd appreciate it if you could guide me on how to export a proper .tex file for the entries via JabRef (or am I supposed to use the file you linked as an example?). Please let me know.

@koppor
Copy link
Member

koppor commented Nov 7, 2019 via email

@michizhou
Copy link
Contributor Author

@koppor I apologize for the relatively long time it took for me to push the latest changes, but I have replaced the erroneous TeXStudio export screenshots with proper ones this time. I also updated the descriptions related to those screenshots accordingly and took care of formatting. Please let me know if further changes are needed before final merging.

@koppor
Copy link
Member

koppor commented Nov 9, 2019

Thank you for the follow up. One Nitpick: The icon in the toolbar does not match the text. The user changed to "TeXStudio". Could you provide an addtional screenshot with texstudio icon circled. Maybe first emacs (as it exists) and then texstudio (new)

grafik

Can you move your additoins to a new file push-to-applications.md? I think, the text is better placed in a separate md file than in "External files", where DOIs and external links are handled.

@michizhou
Copy link
Contributor Author

@koppor I replaced the incorrect Preferences window screenshot with a new one that indicates a user selection for Emacs as their new external viewer application. I also moved all my changes to a new separate file as per your suggestion. I would appreciate your feedback. Thanks!

@koppor
Copy link
Member

koppor commented Nov 9, 2019

Looks good. TeXStudio should always be spelled like that in the text. Moreover, it is an "editor", not a "viewer". Can you please quickly change that?

@michizhou
Copy link
Contributor Author

@koppor I have made the minor edits you pointed out. Please review them when you can.

@koppor koppor merged commit 015271b into JabRef:gh-pages Nov 9, 2019
@koppor
Copy link
Member

koppor commented Nov 9, 2019

Thank you for following up!

I hope, you will continue creating documentation. May I propose https://github.com/JabRef/help.jabref.org/issues/93?

@michizhou
Copy link
Contributor Author

@koppor It was my pleasure. I will definitely consider contributing more documentation in the future. Thank you again for all your help and support for this issue!

@Siedlerchr
Copy link
Member

@michizhou Thanks again for your valuable contribution and! This is very much appreciated and will help the users of JabRef very much!

@michizhou
Copy link
Contributor Author

@Siedlerchr I forgot to ask, but since I have made five PRs (all of which were made in October) that have since been merged, would I be eligible for the JabRef Hacktoberfest swag? If so, I'd greatly appreciate it if you could let me know how to provide my shipping address to claim the swag as well as any other personal information I would need to provide. Thank you.

@koppor
Copy link
Member

koppor commented Nov 14, 2019

@michizhou Thank you for reaching us out. Also with your help the new user documentation page at https://docs.jabref.org/ looks very nice.

We just published a blog post reflecting on #hacktoberfest. -- Find my email address on my GitHub profile. Drop me a short note with your shipping address. Please give us a few weeks to prepare the T-Shirts.

We are currently busy with preparing the 5.0 release. It would be very nice if you continued supporting us so that we can release faster!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants