Re: [PROPOSAL] Quick and easy installation instructions

From: Dan Davison <davison@stats.ox.ac.uk>
To: Carsten Dominik <carsten.dominik@gmail.com>
Cc: emacs org-mode mailing list <emacs-orgmode@gnu.org>
Subject: Re: [PROPOSAL] Quick and easy installation instructions
Date: Mon, 27 Sep 2010 10:00:18 +0100	[thread overview]
Message-ID: <87tylby319.fsf@stats.ox.ac.uk> (raw)
In-Reply-To: <50AE8A48-F8C3-4358-88B2-25CF7A7D15E0@gmail.com> (Carsten Dominik's message of "Mon, 27 Sep 2010 08:26:38 +0200")

Carsten Dominik <carsten.dominik@gmail.com> writes:

> On Sep 26, 2010, at 3:33 PM, Dan Davison wrote:
>
>> I think that the documentation concerning installation should be made
>> more user-friendly. My impression is that the Org manual makes all
>> this
>> sound much harder than it needs to be, and I suspect that this is an
>> entry-barrier for new Org users. For example, the first thing users
>> encounter in the manual section is an instruction to edit a Makefile.
>>
>> I suggest we provide a "quick and easy installation" section to the
>> manual, that shows people how to start using the latest version of
>> Org-mode without messing about with compilation and installation (I
>> rarely compile and have never "installed" Org-mode). It would also be
>> helpful to include notes on how to find your ".emacs" file.
>>
>> This would involve the following changes to section 1.2 Installation:
>>
>> 1. The first thing it should say would be along the lines of
>>   "A reasonably recent version of Org is included in Emacs. Are you
>>   sure you need the latest version of Org?  If not, skip to the
>>   Activation section and start using Org!"
>

Hi Carsten,

> I do agree that we should have this sentence, but maybe modified like
> this:
>
> If you have a recent release of Emacs, a version of Org-mode
> sufficient for all basic use is already included and you may
> skip the installation instructions and continue with section xxx,
> activation.
>
> However, Org-mode evolves fast.  Therefore, we do recommend to install
> the
> most recent release.

OK.

>
> Maybe we could actually have an Emacs command that will insert the
> basic stuff
> into .emacs and optionally compile the Lisp files.
>
> The installation would be:
>
> - download and unpack tar file
> - emacs -l path-to-org.el
> - M-x org-install
>
> org-install would figure out where org.el is, add to .emacs and query
> for compilation.  This wouod make things independent from make and
> other tools.

Yes I wondered about making something like that yesterday (would it make
sense to have emacs do everything, including the download? M-x
org-update-org?). But then I started thinking that we should
investigate/rule out the ELPA possibilities before creating a new
install function for Org. Maybe some people on this list have experience
of maintaining packages on ELPA and will be able to give an opinion.

Dan

>
> Just my 5c
>
> - Carsten
>
>
>>
>> 2. Then we should lay out an easy route and a full route:
>>   1. Quick and easy
>>      Download, set your load-path and (require 'org-install)
>>      Optionally compile (within emacs[1]?)
>>      Suggested text below.
>>   2. Full install
>>      Based on existing instructions
>>
>>
>> What do people think? Is it just the info files which are the issue?
>> What does a single-user machine gain from installation other than info
>> files?
>>
>> Dan
>>
>> Footnotes:
>>
>> [1] How about including in Org-mode a function `org-compile' based on
>> http://orgmode.org/worg/org-hacks.php#compiling-org-without-make
>> and `org-reload'
>>
>>
>> Example quick and Easy installation text:
>> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>
>> 1. Download the latest version
>>   .zip and .tar.gz version are kept at
>>   http://orgmode.org/org-latest.zip
>>   http://orgmode.org/org-latest.tar.gz
>>
>> 2. Extract the archived files
>>   This will create a folder called "org-mode". Let's say that the
>>   location of this folder is "~/path/to/org-mode" (for Windows see
>>   footnote [1])
>>
>> 3. Add the following lines to your .emacs file (note that we're
>> pointing
>>   to the "lisp" folder *within* the main "org-mode" folder):
>>
>>   (setq load-path (cons "~/path/to/org-mode/lisp" load-path)
>>   (require 'org-install)
>>
>> That's it. However, this will not install the latest info files, so
>> these will be out of date (corresponding to whatever version of Org
>> shipped with your emacs). See XXXX for instructions on installing the
>> info files.
>>
>> Now, Emacs should load whatever version of Org-mode you put at
>> "~/path/to/org-mode". So to update Org in the future, simply delete
>> that
>> folder and replace it with a new one (steps 1 and 2 above).
>>
>> Footnotes:
>>
>> [1] On Windows, this path might look something like
>> "C:\\path\to\org-mode"
>>
>> _______________________________________________
>> Emacs-orgmode mailing list
>> Please use `Reply All' to send replies to the list.
>> Emacs-orgmode@gnu.org
>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode