Need a git pull option ... no installation instructions included for mac in Readme.

[EmanuelFaria]

I downloaded the latest version (ami3-2020.08.06_07.01.42-distribution.zip) and read the install.md but I couldn't figure out how to install it on my mac.

Can you add a cloning link to allow a git pull? That would make it much simpler for newbie coders like me. 👍

I wrote an install.md for an earlier version. Perhaps you could use some its content to merge with the install.md being distributed now (I'll zip and attach to this comment. In case the screenshot images aren't embedded, I'll upload a pdf version too.)
MacInstallGuideForGetpapersAndAmi.md.zip
MacInstallGuideForGetpapersAndAmi.pdf

Many thanks for all your hard work making improvments for ami!

Manny

[EmanuelFaria]

Better yet.... is it possible to insert a command such as "ami -update" to have it just do everything automatically?

[petermr]

"to have it just do everything automatically" This is not precisely defined. What is "it"? and what is "everything"? These must be precisely defined before they can be implemented.

…

On Thu, Aug 6, 2020 at 9:20 PM Emanuel Faria ***@***.***> wrote: Better yet.... is it possible to insert a command such as "ami -update" to have it just do everything automatically? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#59 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFTCS56A5BG5HL2HUIV653R7MGBTANCNFSM4PW5N5WQ> .

-- Peter Murray-Rust Founder ContentMine.org and Reader Emeritus in Molecular Informatics Dept. Of Chemistry, University of Cambridge, CB2 1EW, UK

[remkop]

Hi @mannyrules , perhaps we can improve the INSTALL.md instructions on how to run ami commands after unzipping the binary distribution.

The binary distribution should be easier because all you need to do is

• unzip the archive somewhere
• set up the PATH to include the bin/ directory of the location where you unzipped the distribution archive (where the scripts are)

...and you can start using the software. (You do need Java 8 or Java 11 installed.)

What exactly was the issue (or multiple issues) you encountered? To help us troubleshoot, please tell us what you tried, what you expected to happen, and what actually happened.

If you want to take the additional steps of cloning the git project and building from source, take a look at https://github.com/petermr/ami3/blob/master/BUILDING.md for instructions. But a successful build basically results in the same binaries (jar files and scripts) that are in the distribution zip, so I'm not sure why this would be easier.

[EmanuelFaria]

"to have it just do everything automatically" ...

@petermr you’re right. Basically, it would be great to type ami -update and have all the new components downloaded, added or uploaded in the same directories already used by ami, and/or have ami ask the user, step-by-step to complete whatever information is lacking... like paths to directories and defaults to set up (including allocation of RAM, etc. And after that, ask to automatically check to see if their are updates to any of the other “apps” ami relies on (including hit or brew, or anything else.

That’s as much detail as I can describe, given my limited tech vocabulary.

... basically ami -update would walk the user through the steps of making everything ami uses up to date.

_{Sent with GitHawk}

[EmanuelFaria]

Hi @mannyrules , perhaps we can improve the INSTALL.md instructions on how to run ami commands after unzipping the binary distribution. ...

@remkop thanks Remco. That would be a big help to get me going. :)

_{Sent with GitHawk}

[remkop]

@remkop thanks Remco. That would be a big help to get me going. :)

I need your help to do that. :) I thought the instructions were complete/sufficient, but perhaps they are not...

You can help by answering my question:

What exactly was the issue (or multiple issues) you encountered? To help us troubleshoot, please tell us what you tried, what you expected to happen, and what actually happened.

[remkop]

I took another look at the MacInstallGuideForGetpapersAndAmi document you shared (thanks for that).

That document is certainly aimed at a less technology-savvy audience, and I think we can learn from that to improve the current INSTALL.md document. There are some sections in MacInstallGuideForGetpapersAndAmi that no longer apply in recent versions of ami, like Install ami and Install ami default plugins, ignoring those for now.

Action items to improve INSTALL.md:

• java: We should mention that ami requires Java and which version it requires (currently 8 or higher); we add a link to https://java.com/en/download/help/index_installing.xml, from which people should be able to find instructions for their operating system.
• command line: We should mention that ami and getpapers are command line applications and can be used only by typing commands in a terminal emulator program. I hesitate to make the doc too Mac-specific, see the last point in this comment.
• ordering: We should probably move the Dependencies section to after Running AMI.
• example usage: the INSTALL.md should link back to the Running AMI section in the ami README to get people started.

Open questions

dictionaries

Should we add a section on Dictionaries? - @petermr can comment better on whether users need to do anything. Does ami ship with a default set of dictionaries? If so, we can explain this a bit and perhaps point people to where they can get additional ones.

getpapers

The MacInstallGuideForGetpapersAndAmi document has detailed instructions for getpapers. I am not sure about this to be honest. The ami INSTALL.md only mentions it as a dependency and points to https://github.com/ContentMine/getpapers for detailed instructions. I am quite happy with that: if getpapers is changed in the future, we don't need to update our documentation. Does anyone have any thoughts on this?

The MacInstallGuideForGetpapersAndAmi document has a section on Testing getpapers. This is missing in the ContentMine/getpapers README, it may be good to add a section to that project's docs. (Not the ami project docs.)

Mac-specific instructions

I am not sure about adding the Mac-specific text to the general INSTALL.md, interested to hear people's thoughts.

Is is worth creating a separate INSTALL-ON-MAC.md document? Is there any content not covered by the above? Would you be able to help create such a document if you think it should exist?

[remkop]

@mannyrules I updated the INSTALL.md. Please take a look.

[petermr]

Thanks @remko Popma <[email protected]> and @manny A <[email protected]> . Yes, it's a difficult balance. Rik SU did a useful job on getpapers. I remember 6-7 year ago trying to install Node on Windows. It took a day and it didn't work (MacOSX and UNIX were fine). Over the years maven and java have become easier to install . It's reasonable to say to physicists "install Java 8 or later". That works for many bioscientists (and the human genome was solved with perl), but others ?"what's a commandline?" ?huh, don't think I can use *that*!! must have a GUI installer. I agree it's slightly easier to type: apt-get getpapers or brew install getpapers than git pull mvn install , etc. There's also a difference between people who are likely to use this for many months (like you) and a 1-day workshop . For that I use virtual machines or Docker. P.

…

On Fri, Aug 7, 2020 at 10:25 AM Remko Popma ***@***.***> wrote: @mannyrules <https://github.com/mannyrules> I updated the INSTALL.md. Please take a look. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#59 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFTCS37ANOL65RGMYEXZ6TR7PB7HANCNFSM4PW5N5WQ> .

-- Peter Murray-Rust Founder ContentMine.org and Reader Emeritus in Molecular Informatics Dept. Of Chemistry, University of Cambridge, CB2 1EW, UK

[EmanuelFaria]

Hi @remkop ,
Thanks for helping with this.
I looked at the updated .md — I think — I'm afraid I'm still lost, however.

To me, there sees to be something missing in this part of the instructions in the .md file I just looked at (Copied below. I don't know how to increase the quote level in this message to make it stand out.

----------------- quoted text from current .md file starts here --------------------
After unzipping the distribution archive, you will find two directories:

bin which contains the launcher scripts for running ami commands.
repo which contains all the required jar library files.
To use ami, execute the scripts in the bin/ directory. Good starting points are the ami and amidict commands. Try the online help to get an overview of the available options and subcommands:

cd ami3-2020.07.25_09.02.10/bin/
ami --help

--------------------quoted text from current .md file ends here-------------------

I think what's missing (I'm guessing here) is something along the lines of:

a) unzip the file and move the newly unzipped folder in the directory of your home folder where you intend to store the "guts" of ami -- from this point on, ami will refer to this location in the background when it runs, so don't move or rename it from this place. In my case, it's:

/Users/emanuelfarruda/DAVEapps/ami3-2020.08.07_07.13.18/bin

b) run some command (sudo?? cd??) in combination with that path to [get ami to do something]

c) when you see [something happen], type [this command] to do a self-test. If you see [this thing happen], you're good to go. If not, [do this].

What would be nice is the ability to have it done automatically, Is it possible to do that? Or one of the following options:

a) with the git pull, as was in the .md file I made (copied below).
b) build right into ami the ability to automatically update itself the moment ami is launched (the way homebrew does)
c) write a new instruction like ami -update and let ami get the latest version and do all the work in the background
d) include an "INSTALLME.MAC" executable file in the zipped package that I could double-click to launch and take care of the rest?

---------------- quoted text from my .md file starts here ----------------

We will now use Git to install ami by “cloning” it using the following steps:

1. Go to https://github.com/ContentMine/ami 

2. Copy and paste (or type) the following command into Terminal, then hit return/enter to let it install.

git clone https://github.com/petermr/ami-jars2.git

---------------- quoted text from my .md file ends here ----------------

I don't have a clue how much any of these options are, but whichever is the least work for new users going forward would likely be the best investment of time. I just don't know how this stands as a priority related to all the other open issues though. My guess is it would be the git pull option.

Thanks again.

M.

[remkop]

@mannyrules To be honest, I am getting a bit confused. Are you (yourself) unable to get ami up and running with the INSTALL.md instructions, or are you helping us improve the instructions for other people? I am guessing the latter, can you clarify?

I think what's missing (I'm guessing here) is something along the lines of:
a) unzip the file and move the newly unzipped folder in the directory of your home folder where you intend to store the "guts" of ami -- from this point on, ami will refer to this location in the background when it runs, so don't move or rename it from this place.

Hmm... maybe too much hand-holding. There is no "in the background", so that is confusing. "don't move or rename it from this place" - sure, this is obvious. If users make that mistake that is part of the learning process of operating a computer, not of using ami.

b) run some command (sudo?? cd??) in combination with that path to [get ami to do something]

c) when you see [something happen], type [this command] to do a self-test. If you see [this thing happen], you're good to go. If not, [do this].

This is covered in the Running AMI section: cd into the directory and use ami --help and ami --version to verify the installation. Expected results are mentioned.

What would be nice is the ability to have it done automatically, Is it possible to do that?

I did some work on adding a script for setting the PATH automatically, but this turned out to be trickier than I thought, so I just updated the INSTALL instructions for now.

I don't see myself working on automating the install further. Happy to review pull requests by anyone who wants to contribute in this area.

[EmanuelFaria]

Hi Remko, sorry for the delay in responding to you.

No worries. Peter and I did a screen-share, and he walked me through installing on my mac. I made a screen recording, so as soon as I can, I'll distill the steps that got us across the finish line, and post them (propose them?) for inclusion in the instructions.

Thanks again

Manny