Re: Elpa installation fails and general confusion

[salotz]

Thanks for your help Stephen.

On installation failure:
------------------------

> This indicates that you have old ada-mode code in your load-path
> somewhere, or an incomplete package install.
> 
> That variable is defined in wisi-parse-common.el, in the 'wisi' ELPA
> package, which ada-mode installs as a dependency (as you noted above).
> 
> First, try restarting emacs.

I had already tried restarting emacs. I also uninstalled both ada-mode
and wisi and reinstalled from scratch each time.

> 
> If that doesn't help, do:
> 
> M-x locate-library wisi-parse-common
> 
> That should report ~/.emacs.d/elpa/wisi-3.1.3/wisi-prj.elc

Running this I get: 

```
Library is file ~/.emacs.d/elpa/wisi-3.1.3/wisi-parse-common.elc
```
 

I should have mentioned before but I get these Errors/Warnings when I
`package-install wisi` from elpa:

```

In toplevel form:
wisi-parse-common.el:39:3:Warning: reference to free variable ‘pos’
wisi-parse-common.el:40:3:Warning: reference to free variable ‘message’
wisi-parse-common.el:41:3:Warning: reference to free variable ‘inserted’
wisi-parse-common.el:47:3:Warning: reference to free variable ‘deleted’
wisi-parse-common.el:48:3:Warning: reference to free variable
‘deleted-region’
wisi-parse-common.el:56:3:Warning: reference to free variable ‘repair’
wisi-parse-common.el:59:15:Warning: reference to free variable
‘wisi-parser’
wisi-parse-common.el:63:3:Warning: reference to free variable
‘lexer-errors’
wisi-parse-common.el:66:3:Warning: reference to free variable
‘parse-errors’
wisi-parse-common.el:70:3:Warning: reference to free variable
‘repair-image’

In end of data:
wisi-parse-common.el:404:1:Warning: the function ‘cl-defstruct’ might
not be
    defined at runtime.
wisi-parse-common.el:404:1:Warning: the following functions are not
known to
    be defined: wisi--lexer-error, wisi--parse-error-repair,
wisi--parse-error

In toplevel form:
wisi-prj.el:30:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
wisi-process-parse.el:23:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
wisi-run-indent-test.el:20:1:Error: Symbol’s function definition is
void: wisi--lexer-error

In toplevel form:
wisi-skel.el:78:1:Warning: Unused lexical variable ‘wisi-inhibit-parse’

In wisi-skel-expand:
wisi-skel.el:128:15:Warning: reference to free variable ‘wisi-auto-case’

In end of data:
wisi-skel.el:188:1:Warning: the function ‘wisi-case-adjust-region’ is
not
    known to be defined.

In toplevel form:
wisi-tests.el:25:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
wisi.el:111:1:Error: Symbol’s function definition is void:
wisi--lexer-error

```

And then installing ada-mode:

```

In toplevel form:
ada-build.el:37:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
ada-compiler-gnat.el:33:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
ada-core.el:26:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
ada-gnat-xref.el:37:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
ada-imenu.el:27:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
ada-mode.el:107:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
ada-prj.el:7:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
ada-process.el:19:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
ada-stmt.el:7:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
ada-xref.el:8:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
gnat-core.el:27:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
gpr-mode.el:38:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
gpr-process.el:19:1:Error: Symbol’s function definition is void:
wisi--lexer-error

In toplevel form:
gpr-query.el:32:1:Error: Symbol’s function definition is void:
wisi--lexer-error

```


As for the general confusion topics:
------------------------------------


> They are documented, in the Install section of the ada-mode manual,
> which is mentioned in README.
> 
> Where did you look for this documentation? What can we do to make it
> more likely that you would have found it?

I think its due to there being multiple documentation sites. I was
looking here for instructions:
https://www.gnu.org/software/emacs/manual/html_mono/ada-mode.html#Installation

As opposed to your official docs:
http://www.nongnu.org/ada-mode/ada-mode.html#Ada-executables

The hyperlink for that is `ada-mode.html`, this should be
"Documentation". If there is derelict docs on the web, you should
mention that and say stay away and put the hyperlink to it. Explain
that ada-mode has not been distributed with emacs since v??. When I was
looking at all this I just started to get the feeling that I couldn't
believe any of it, I didn't know what was true and what was not.

At the top of the page you list out the requirements and installation
instructions:

```
Requires Emacs 25.0 or greater. Compiling the required Ada code for the
requires GNAT GPL 2017 or later; tested with GNAT Community Edition
2019 and GNAT Pro 20.
To install:
Enable packages in your ~/.emacs: (package-initialize)
Invoke M-x list-packages, select ada-mode 7.1.3, install.
In a bash shell:
cd ~/.emacs.d/elpa/ada-mode-i.j.k
./build.sh
./install.sh
```

Its very misleading to have partial instructions somewhere. I would
remove this and just link directly to that section in the manual.

It would still be nice to add in distro specific install instructions
since that makes things a lot easier for a good chunk of people that are
installing this.

This is a bigger issue but it ties into this. There are
a lot of steps to installing this major mode. I think too many,
especially for someone that is getting into Ada for the first time.
Most major editing modes are just a simple elpa install and you get
syntax highlighting and some help with indentation. This is all I was
after, and the time I've put into getting it is not going to pay off
for a while since I'm not going to use the advanced features right away
(or ever perhaps).

I know this adds complexity from the distribution standpoint but
perhaps having a single elisp file for the major mode that gives these
basic features would make for a simpler experience overall. Then you
can distribute the fancier, more finnicky one as a separate package. 

In fact if you can point me to such an elisp file it would be much
appreciated :)



> > The NEWS page there however is listing the 30 Jan 2020 release as
> > 7.0.1 (http://www.nongnu.org/ada-mode/NEWS-ada-mode.text). Would be
> > nice if this was up to date.  
> 
> Thanks for catching this; fixed now.
> 
> > The tarball downloads page in savannah doesn't have any labelled
> > 7.1.3. It looks like the latest there is 7.0.1 like the NEWS page.  
> 
> Hmm. Apparenty I've been forgetting to upload for a while. I'll be
> sure to upload the next time. Note that these tarballs are redundant
> with the git repository, and no one is expected to install from them.

I realized they are redundant since elpa install should work, but my
logic is that if elpa is broken (for reasons specific to elpa such as
the recipe etc.) I can always write a script to install manually from
those tarballs. For example, I thought maybe that the 7.1.4 release
on ELPA was in some error and that I should be using 7.1.3 since that
is what is on the main page. But you can't install old versions with
package-install (ugh).

For some projects its just easier to add external elisp to my paths
with a script rather than go through the package system, especially
when I have to run compilation on them.

If your referring to this line: 

```
To clone the git repository, use "git clone -b org.emacs.ada-mode";
otherwise git uses the non-existent branch "master". After cloning that
branch, run git_checkout.sh to checkout wisitoken, sal, etc.
```

I thought this was for development. I thought projects distribute
archives without the expectation that a target will have git installed
(or knowledge of git). Especially when the tarballs are also
advertised. I guess another part of installation instructions would be
how to do from the source archives. I failed at this because I didn't
have SAL and other dependencies and its confusing because for ELPA
install these come along somehow. Ie. there isn't a mapping of wisi
tarball -> elpa wisi package and ada-mode tarball -> elpa ada-mode
package.

Sorry this is such a long post about boring things, but hopefully the
perspective helps.

~Sam