Re: [PROPOSAL] Quick and easy installation instructions

From: Carsten Dominik <carsten.dominik@gmail.com>
To: Dan Davison <davison@stats.ox.ac.uk>
Cc: emacs org-mode mailing list <emacs-orgmode@gnu.org>
Subject: Re: [PROPOSAL] Quick and easy installation instructions
Date: Mon, 27 Sep 2010 11:55:54 +0200	[thread overview]
Message-ID: <33E4DC13-3B6B-4803-9F00-2FB440F912C1@gmail.com> (raw)
In-Reply-To: <87tylby319.fsf@stats.ox.ac.uk>

On Sep 27, 2010, at 11:00 AM, Dan Davison wrote:

> 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?

This rings a bell - I think Sebastian Rose implemented that already.   
Let search!

- Carsten

> 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