Re: Legacy scripted installation, was Re: LilyPond 2.23.14

[David Wright]

On Wed 19 Oct 2022 at 06:46:22 (-0700), Knute Snortum wrote:
> On Tue, Oct 18, 2022 at 11:21 AM David Wright wrote:
> > On Tue 18 Oct 2022 at 05:15:31 (-0400), Craig Bakalian wrote:
> > >
> > > And could we please release the latest greatest lilypond as a shell
> > > script like it used to be released.
> >
> > You seemed to be happy enough when you wrote
> > https://lists.gnu.org/archive/html/lilypond-user/2022-09/msg00071.html
> >
> > Can you tell us what has changed. Is it the shell script itself that
> > you miss, or the attempt to download the documentation, or the
> > uninstall script? Unless you tell us what you miss, there's not much
> > more that can be done except to say "Ain't gonna happen", aka WONTFIX.
> 
> I'll jump in here if it's all right.  Craig, did you notice that
> there's an installation[1] page that you can get to from the download
> page?  I missed that at first.  The command-line installation
> instructions are rather terse, but I guess the assumption is that if
> you're using the command-line, you know how to run tar, mv directories
> around, add things to the PATH, etc.  But is that a good assumption?

(Disclaimer: I'm speaking only to the linux version.)

The stable version seems to get this right:
  http://lilypond.org/
  http://lilypond.org/download.html
  http://lilypond.org/unix.html
and here we get instructions for using the old script
method to install a downloaded version of LilyPond.

The unstable version seems in need of some tweaking:
  http://lilypond.org/
  http://lilypond.org/development.html
and here we see:

  Instructions for git and compiling are in the Contributor’s Guide.
    lilypond git repository
  Documentation writers and testers will generally want to download the latest 
binary:
    GNU/Linux x86_64: LilyPond 2.23.14
    [ … ]
  If you are unsure about how to install these binaries,
  please read the start of the Learning manual.

Conventional wisdom is that development versions are for more than
just documentation writers and testers. But even sophisticated LP
users might be unsure about how to deal with a .tar.gz file. So
I would at least move the last paragraph to before the download
links, though an alternative would be to copy stable's approach
and make the "GNU/Linux x86_64: LilyPond 2.23.14" link open its
own unix-only page.

I would collect the git, compiling and Source information together,
and place it at the end of the Download panel, out of the way for
the great majority of users. (Accidentally unpacking the source
could be very confusing, as its top-level directory has the same
name as the binary's.)

Moving on to:
  http://lilypond.org/doc/v2.23/Documentation/learning/index.html
itself. For a graphical setup:
  
http://lilypond.org/doc/v2.23/Documentation/learning/graphical-setup-under-gnu_002flinux
the instructions are interesting as they rely on a distribution's
versions of LP and Fresco in the first place, before tackling
the addition of a development version. But not running a DE, I'm
not really qualified to comment further.

For running LP from the command-line:
  http://lilypond.org/doc/v2.23/Documentation/learning/command-line-setup
you get the following:

  1.4 Command line setup

  On many GNU/Linux distributions, LilyPond can be installed from
  the package manager. This is also the case on macOS using either
  MacPorts or Homebrew.

  In any case, you can install LilyPond by downloading the archive
  from Download and unpacking it. The binaries are usable
  immediately after unpacking. You can run

    /.../lilypond-x.y.z/bin/lilypond file.ly

  (on Windows, replace the slashes ‘/’ with backslashes ‘\’).

The first sentence seems odd: I presume that package managers can only
install distributions' versions (eg Debian can install .debs, or rpms
etc converted by alien), and they're unlikely to comprise the latest
development version. And "In any case" seems an odd way to introduce
the reason that most people will visit the page in the first place;
kind of "well, you're here now, so you might as well know that …).

Wouldn't it be better to write first about what to do with a .tar.gz
binary. For a typical single user, suggest they unpack it in their
home directory, with   tar xf …/lilypond-N.N.N-linux-x86_64.tar.gz
(or tar xvf to see the filenames as they're unpacked).¹ The top-level
directory can then be moved/renamed as desired, without the
side-effects that might have happened in the past with the old
script method.

Perhaps also suggest that someone installing LP for all the users on
a system should unpack it as root in a directory like /usr/local/bin/
or /opt/, or as recommended by their distribution or tradition.

It might also be fair to refer to the https://frescobaldi.org/download
page for those who want to run LP from Fresco but still by way of a
terminal's command line.

I don't know how much any of this applies to command line Windows
and Macs, but I guess the OP might like to comment on whether
such changes might have helped.

> I do think the tarball could benefit from having a README file with
> even just this text:

I'm not sure that embedding a README inside the archive would be
very useful to someone staring at a .tar.gz file and not already
knowing how to deal with it. After all, it has to be at least
two levels deep, like the licences.

¹ I don't know whether being this specific means that we should also
  mention that the documentation requires an extra J or --xz option
  as it's a .tar.xz tarball (presently—sometimes they have been .bz2).

Cheers,
David.