Re: [PROPOSAL] Quick and easy installation instructions

From: Richard Riley <rileyrg@gmail.com>
To: emacs-orgmode@gnu.org
Subject: Re: [PROPOSAL] Quick and easy installation instructions
Date: Sun, 26 Sep 2010 16:21:18 +0200	[thread overview]
Message-ID: <i7nkt2$otu$1@dough.gmane.org> (raw)
In-Reply-To: 87tylcy6gw.fsf@stats.ox.ac.uk

Dan Davison <davison@stats.ox.ac.uk> writes:

> 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!"

I would not go that way. org moves very very quickly.

I would have it in bold letters "we thoroughly recommend taking the
latest org release from git and here is how to do it (git pull with a
label)". Then if and when issues arise they can git pull as and when the
fixes arrive.

I say this because some distros (debian being the prime example) can be
very tardy with including latest versions.

And someone who uses emacs would not be overly put out by git installing
or unzipping I think.

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

I would leave out the compile all together : advanced users who might
need it will know how to do it. old elc files are a frequent issue with
beginners that rears its ugly head time and time again.

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

Info files are the issue. The addition to the infopath of the new info
files is frequently an issue too. I say that because emacs info is my
nemesis : I have never *properly* understood the way dir files work and
frequently spend ages scratching my head as to where info files should
really go ;)

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

-- 
☘ http://www.shamrockirishbar.com, http://splash-of-open-sauce.blogspot.com/ http://www.richardriley.net