[PROPOSAL] Quick and easy installation instructions

[PROPOSAL] Quick and easy installation instructions

[Dan Davison]

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

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"

Re: [PROPOSAL] Quick and easy installation instructions

[Thomas S. Dye]

On Sep 26, 2010, at 3:33 AM, 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!"
>
> 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"

+1

Tom

Re: [PROPOSAL] Quick and easy installation instructions

[A. Ryan Reynolds]

On Sun, Sep 26, 2010 at 8:33 AM, Dan Davison <davison@stats.ox.ac.uk> wrote:
> 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

It might also be helpful to make note of the fact that some Linux
distributions offer packages of newer versions of Org than the
Emacs-included versions. For instance, on Debian testing, 7.01g is
available to me in a package (and 7.01h if I install from unstable). I
assume this probably trickles down to Ubuntu as well. This is the
route I take because it keeps me relatively close to Org-mode
developments without having to take the time to manage source code.

-- 
A. Ryan Reynolds

Re: [PROPOSAL] Quick and easy installation instructions

[Richard Riley]

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

Re: [PROPOSAL] Quick and easy installation instructions

[Dan Davison]

Hi Richard,

Richard Riley <rileyrg@gmail.com> writes:

> 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 do understand why you say this, but these are supposed to be easy
instructions; they should not involve usage of any version control
software. 

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

Yes, I agree. The org-latest.{zip,tgz} are what should be recommended
(with the info caveat)

> And someone who uses emacs would not be overly put out by git installing

I think that statement requires some modification. For starters, I don't
think either of us use Windows, but I gather that git is not exactly
easy to use on Windows.

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

Sounds good to me. I have an intel atom processor and I don't find
myself wanting to compile for extra speed.

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

Hmm, well I'm glad it's not just me :) But I think it would be OK if we
made it clear that, if they are following the easy route, they should
use the html/pdf documentation on the website.

Dan

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

Re: Re: [PROPOSAL] Quick and easy installation instructions

[Carsten Dominik]

On Sep 26, 2010, at 4:52 PM, Dan Davison wrote:

> Hi Richard,
>
> Richard Riley <rileyrg@gmail.com> writes:
>
>> 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 do understand why you say this, but these are supposed to be easy
> instructions; they should not involve usage of any version control
> software.
>
>> I say this because some distros (debian being the prime example)  
>> can be
>> very tardy with including latest versions.
>
> Yes, I agree. The org-latest.{zip,tgz} are what should be recommended
> (with the info caveat)

I think what we should recommend here is org.tar.gz and org.zip.  There
are the latest release, usually no more that 1 or 2 months old and  
stable.
Using the ..-latest files does carry this risk of making a beginner  
install
a bad version.  So if we go for beginners...

- Carsten

Re: [PROPOSAL] Quick and easy installation instructions

[Richard Riley]

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

> Hi Richard,
>
> Richard Riley <rileyrg@gmail.com> writes:
>
>> 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 ;)
>
> Hmm, well I'm glad it's not just me :) But I think it would be OK if
> we

You have no idea how pleased I am to hear you say that ... I sometimes
wondered if I should go back to notepad ;) When asking the #emacs irc it
seemed I was the only one in the world that constantly had issues. Of
course mentioning "Debian" immediately saw me get the "oh debian" cold
shoulder ... ;) LOL.

Good points about Windows too btw. Easy to forget sometimes.

> made it clear that, if they are following the easy route, they should
> use the html/pdf documentation on the website.
>
> Dan

Re: [PROPOSAL] Quick and easy installation instructions

[Rémi Vanicat]

Richard Riley <rileyrg@gmail.com> writes:

> You have no idea how pleased I am to hear you say that ... I sometimes
> wondered if I should go back to notepad ;) When asking the #emacs irc it
> seemed I was the only one in the world that constantly had issues. Of
> course mentioning "Debian" immediately saw me get the "oh debian" cold
> shoulder ... ;) LOL.

On Debian you should use update-info-dir ( as in
$ update-info-dir /path/to/infos
to generate the dir file. (This may work on others distribution too, I
don't know if it is a Debian specific tools)
[...]


-- 
Rémi Vanicat

Re: [PROPOSAL] Quick and easy installation instructions

[Richard Riley]

Rémi Vanicat <vanicat@debian.org> writes:

> Richard Riley <rileyrg@gmail.com> writes:
>
>> You have no idea how pleased I am to hear you say that ... I sometimes
>> wondered if I should go back to notepad ;) When asking the #emacs irc it
>> seemed I was the only one in the world that constantly had issues. Of
>> course mentioning "Debian" immediately saw me get the "oh debian" cold
>> shoulder ... ;) LOL.
>
> On Debian you should use update-info-dir ( as in
> $ update-info-dir /path/to/infos
> to generate the dir file. (This may work on others distribution too, I
> don't know if it is a Debian specific tools)
> [...]

Yes, I knew about that and thing I submitted an update for the makefile
yonks ago to use just that. The issue seemed to be with multiple dirs
and then emacs having its own info file paths. I need to get back to building
my own emacs on debian and see what happens to be more explicit - I just
know that I, and from #emacs, others ended up in a kind of pickle.

Re: Re: [PROPOSAL] Quick and easy installation instructions

[Adam]

On Monday 27 September 2010 02:52 am, Dan Davison wrote:
> Hi Richard,
>
> Richard Riley <rileyrg@gmail.com> writes:
> > 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 do understand why you say this, but these are supposed to be easy
> instructions; they should not involve usage of any version control
> software.
>
> > I say this because some distros (debian being the prime example) can be
> > very tardy with including latest versions.
>
> Yes, I agree. The org-latest.{zip,tgz} are what should be recommended
> (with the info caveat)
>
> > And someone who uses emacs would not be overly put out by git installing
>
> I think that statement requires some modification. For starters, I don't
> think either of us use Windows, but I gather that git is not exactly
> easy to use on Windows.

I agree.   On my Windows machine, (and Emacs with org-mode work 
well there),  it was a case of getting the zipped org-mode package, 
unzipping into a suitable directory  (C:\emacs\orgx  or  C:
\home\emacs\lisp\orgx  etc), and then  add-to-list;  load-path  
and require 'org-install,  and maybe a require 'org (not sure). 

After that, then adding org agenda files paths, diary etc. 

This uses no Git.   And I didn't realize how simple upgrading to a newer  
orgmode could be.  Compiling isn't important at this stage. 


> > 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.
>
> Sounds good to me. I have an intel atom processor and I don't find
> myself wanting to compile for extra speed.
>
> >> 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 ;)
>
> Hmm, well I'm glad it's not just me :) But I think it would be OK if we
> made it clear that, if they are following the easy route, they should
> use the html/pdf documentation on the website.
>
> Dan
>
> >> 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

Re: [PROPOSAL] Quick and easy installation instructions

[John Hendy]

[-- Attachment #1.1: Type: text/plain, Size: 2458 bytes --]

On Sun, Sep 26, 2010 at 8:33 AM, Dan Davison <davison@stats.ox.ac.uk> 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...


Very cool idea! This would probably get quite redundant... but I wonder
about "extras" as well. Early in my Org-mode experience I would see "cool"
things like ditaa or gnuplot and want to get set up. While there are often
references to other documentation sets, I won't say that things were exactly
easy. Anyway, again this will be somewhat redundant since other groups
maintain their own documentation, but I could see a good in keeping some
kind of Worg section on "modular functionality" with some help for that?


John



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

[-- Attachment #1.2: Type: text/html, Size: 3446 bytes --]

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
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

Re: [PROPOSAL] Quick and easy installation instructions

[Achim Gratz]

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.

Agreed.  It was easy enough to follow for me, but I can see that others
may find it too technical.

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

Just as a counter-point, I always compile and install (even bleeding
edge, that just goes into a different place) because that allows me to
separate production from experimental code more easily.

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

Don't assume what version of Emacs the user may have and it may be
configured in crazy ways, too.  To read the instructions one would
already have had to find and go to orgmode.org, so there is little
further effort to fix them up with the latest stable version.  Right now
there is no official Emacs release that uses Org 7.x, for instance.

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

I'd really suggest putting it into site-lisp as that removes the need to
muck about with load-path (which isn't customizable...), the dangers of
which you demonstrate yourself:

>    (setq load-path (cons "~/path/to/org-mode/lisp" load-path)

(yes, just a missing closing paren).  The other thing of course is that
by putting it there all other users on the system will benefit from it.
That's a plus even under Windows.

While we are at it, I think both org and org-babel have enough files to
better go into sub-directories (maybe org-install should stay on
top-level).


Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptation for Waldorf Blofeld V1.15B11:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

Re: [PROPOSAL] Quick and easy installation instructions

[Dan Davison]

Achim Gratz <Stromeko@nexgo.de> writes:

> 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.
>
> Agreed.  It was easy enough to follow for me, but I can see that others
> may find it too technical.

Hi Achim,

OK, so we're agreed. But your points below don't seem to describe a less
technical route. Could you describe the less technical version of the
instructions for the method that you are advocating?

Dan

>
>> 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.
>
> Just as a counter-point, I always compile and install (even bleeding
> edge, that just goes into a different place) because that allows me to
> separate production from experimental code more easily.
>
>> 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!"
>
> Don't assume what version of Emacs the user may have and it may be
> configured in crazy ways, too.  To read the instructions one would
> already have had to find and go to orgmode.org, so there is little
> further effort to fix them up with the latest stable version.  Right now
> there is no official Emacs release that uses Org 7.x, for instance.
>
>> 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.
>
> I'd really suggest putting it into site-lisp as that removes the need to
> muck about with load-path (which isn't customizable...), the dangers of
> which you demonstrate yourself:
>
>>    (setq load-path (cons "~/path/to/org-mode/lisp" load-path)
>
> (yes, just a missing closing paren).  The other thing of course is that
> by putting it there all other users on the system will benefit from it.
> That's a plus even under Windows.

>
> While we are at it, I think both org and org-babel have enough files to
> better go into sub-directories (maybe org-install should stay on
> top-level).
>
>
> Achim.

Re: [PROPOSAL] Quick and easy installation instructions

[Achim Gratz]

Dan Davison <davison@stats.ox.ac.uk> writes:
> OK, so we're agreed. But your points below don't seem to describe a less
> technical route. Could you describe the less technical version of the
> instructions for the method that you are advocating?

Installing is something technical and I'm a tech-head, so you're asking
something of me I'm not really qualified to do. :-)

My points were:

- I think that a proper installation via make is the way to go, but I
  recognize that some folks don't want or need to do that.

- There is a default place where Emacs expects this kind of stuff and
  has some magic implemented to make it work without further
  configuration, and that place is site-lisp.  You can put it someplace
  else, but then you have to alter the load-path or you are at the mercy
  of some special configuration to make the same magic work in other
  places, too (I've had ~/lisp set up that way when I was still
  compiling Emacs myself).

- If org was delivered and compiled in 'org/' rather than 'lisp/', one
  could instruct users to just take that folder and copy/drag it into
  the site-lisp directory of their Emacs installation.  You can do that
  with the lisp folder, but I'd at least tell people to please rename it
  to org after doing the copy.

If you want to get any less technical than that, I'd suggest ELPA or
something like it (as has been discussed already in another thread).
ELPA packages build and configure themselves as far as possible, so that
should take out the guesswork for novice users.  Also it looks like it
will come standard with Emacs24 (with a GNU archive and the possibility
to add additional archives, which could take care of the "bleeding
edge"), so there will be absolutely no "installation" work required from
the user from then on.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

DIY Stuff:
http://Synth.Stromeko.net/DIY.html

ELPA [WAS] Re: [PROPOSAL] Quick and easy installation instructions

[Dan Davison]

Achim Gratz <Stromeko@nexgo.de> writes:

> Dan Davison <davison@stats.ox.ac.uk> writes:
>> OK, so we're agreed. But your points below don't seem to describe a less
>> technical route. Could you describe the less technical version of the
>> instructions for the method that you are advocating?
>
> Installing is something technical and I'm a tech-head, so you're asking
> something of me I'm not really qualified to do. :-)
>
> My points were:
>
> - I think that a proper installation via make is the way to go, but I
>   recognize that some folks don't want or need to do that.
>
> - There is a default place where Emacs expects this kind of stuff and
>   has some magic implemented to make it work without further
>   configuration, and that place is site-lisp.  You can put it someplace
>   else, but then you have to alter the load-path or you are at the mercy
>   of some special configuration to make the same magic work in other
>   places, too (I've had ~/lisp set up that way when I was still
>   compiling Emacs myself).
>
> - If org was delivered and compiled in 'org/' rather than 'lisp/', one
>   could instruct users to just take that folder and copy/drag it into
>   the site-lisp directory of their Emacs installation.  You can do that
>   with the lisp folder, but I'd at least tell people to please rename it
>   to org after doing the copy.
>
> If you want to get any less technical than that, I'd suggest ELPA or
> something like it (as has been discussed already in another thread).
> ELPA packages build and configure themselves as far as possible, so that
> should take out the guesswork for novice users.  Also it looks like it
> will come standard with Emacs24 (with a GNU archive and the possibility
> to add additional archives, which could take care of the "bleeding
> edge"), so there will be absolutely no "installation" work required from
> the user from then on.

Hi Achim,

Thanks, that was very helpful.

Using ELPA does seem like an attractive route, especially if it
(package.el) is going to be in Emacs24.

- How much work would it take to put and maintain Org-mode on ELPA?
- Would it make sense to have two different packages available via ELPA,
  i.e. Latest Release and Latest?
- Will it be possible for the Org project to have control over the files
  that ELPA points at (in which case we might be able to keep the latest
  updated a few times a day or something), or do we have to submit them
  to a server that's out of our control?
- Will ELPA be able to get the info files installed suitably?

Dan

>
>
> Regards,
> Achim.

Re: ELPA [WAS] Re: [PROPOSAL] Quick and easy installation instructions

[Scot Becker]

Dan,

I have no special expertise on this, but I'll hazzard an answer as a
simple ELPA user:

> Using ELPA does seem like an attractive route, especially if it
> (package.el) is going to be in Emacs24.

To me too, ELPA is a great idea.  It probably needs some perfecting,
but if it works for these purposes, we only help the perfecting by
encouraging it's use.

> - How much work would it take to put and maintain Org-mode on ELPA?

I'll let someone else answer that, but I'd be suprised if it couldn't
be automated.

> - Would it make sense to have two different packages available via ELPA,

To me, yes.  I like using git for the development tree, but I expect
that ELPA makes for a nice way for Windows users (and others who don't
want to or can't use git) to get the latest version easily (and
possibly even to downgrade if necessary).  The latest release version
is of course necessary as well, since using it is the main
recommendation to new users.

> - Will it be possible for the Org project to have control over the files

An excellent and important question.  We'd rather not be dependent on
personal intervention from others to update, especially the '-latest'
version.  And even for the releases, we'd probably be glad to see them
propagate to the repository pretty quickly.  (The current non-gnu ELPA
repo only updates every two weeks or so.  This is fine for many
projects, but probably not enough even for org-mode releases.)

> - Will ELPA be able to get the info files installed suitably?

In principle, yes.  ELPA does concern itself with both the load-path
and the info-path.

Scot

Re: ELPA [WAS] Re: [PROPOSAL] Quick and easy installation instructions

[Jambunathan K]

> Dan,
>
> I have no special expertise on this, but I'll hazzard an answer as a
> simple ELPA user:
>
>> Using ELPA does seem like an attractive route, especially if it
>> (package.el) is going to be in Emacs24.
>
> To me too, ELPA is a great idea.  It probably needs some perfecting,
> but if it works for these purposes, we only help the perfecting by
> encouraging it's use.
>
>> - How much work would it take to put and maintain Org-mode on ELPA?
>
> I'll let someone else answer that, but I'd be suprised if it couldn't
> be automated.
>
>> - Would it make sense to have two different packages available via ELPA,
>
> To me, yes.  I like using git for the development tree, but I expect
> that ELPA makes for a nice way for Windows users (and others who don't
> want to or can't use git) to get the latest version easily (and
> possibly even to downgrade if necessary).  The latest release version
> is of course necessary as well, since using it is the main
> recommendation to new users.
>
>> - Will it be possible for the Org project to have control over the files
>
> An excellent and important question.  We'd rather not be dependent on
> personal intervention from others to update, especially the '-latest'
> version.  And even for the releases, we'd probably be glad to see them
> propagate to the repository pretty quickly.  (The current non-gnu ELPA
> repo only updates every two weeks or so.  This is fine for many
> projects, but probably not enough even for org-mode releases.)
>
>> - Will ELPA be able to get the info files installed suitably?
>
> In principle, yes.  ELPA does concern itself with both the load-path
> and the info-path.
>

FWIW the info entry and elisp file for the package manager answers some
of the questions raised here.

Base URL: http://github.com/davidswelt/aquamacs-emacs/raw/aquamacs24

./lisp/emacs-lisp/package.el
./lisp/emacs-lisp/package-x.el

./doc/lispref/package.texi

I see that default archive is set to 

    http://elpa.gnu.org/packages/

Atleast from the browser I could see only a handful of files. No I don't
see Orgmode there. It wouldn't be there unless someone provided *-pkg.el
file.

ELPA that I have installed with my emacs-23.1.91 is from
    http://tromey.com/elpa/. 

As a user, I find the experience of using package manager extremely
pleasant. Apart from merge related changes & related renaming, I believe
the emacs24 version should be just the same. 

Since package manager is a new kid on the block I don't see any reason
why it can't be taught new tricks.

ps: There are references to 'uploads' in package-x.el. So, there is
reason to believe that there exists support for updating archives
remotely.

Jambunathan K.

> Scot

Re: ELPA

[Eric Schulte]

Scot Becker <scot.becker@gmail.com> writes:

> Dan,

[...]

>> - Would it make sense to have two different packages available via ELPA,
>
> To me, yes.  I like using git for the development tree, but I expect
> that ELPA makes for a nice way for Windows users (and others who don't
> want to or can't use git) to get the latest version easily (and
> possibly even to downgrade if necessary).  The latest release version
> is of course necessary as well, since using it is the main
> recommendation to new users.
>

I would think that it only makes sense to have one Org-mode package in
ELPA, namely the bleeding edge git version of Org-mode.  ELPA serves as
a way to distribute packages which are not (or can't be) part of Emacs,
I don't think it makes sense to use ELPA to re-distribute the version of
Org-mode which users already have installed as part of their Emacs
install.  Un-installing the bleeding edge Org-mode would be equivalent
to downgrading to the Emacs version.

Also, I would tend to think that this would make the most sense if we
automate the ELPA integration s.t. every time a new revision is pushed
up the to git repository, the ELPA version is automatically upgraded
(with a git commit hook).  If this isn't currently possible in ELPA then
I'd agree with a point Jambunathan makes in this thread that this is a
trick we can help ELPA to learn.

The reason I think the above is important is that very frequently the
answer to a question is "oh, I fixed that, please pull the latest from
git", and we'll be constantly frustrating users if ELPA can't keep up
with git.

Best -- Eric

Re: ELPA

[Sebastian Rose]

"Eric Schulte" <schulte.eric@gmail.com> writes:
> I would think that it only makes sense to have one Org-mode package in
> ELPA, namely the bleeding edge git version of Org-mode.  ELPA serves as
> a way to distribute packages which are not (or can't be) part of Emacs,


package.el in emacs-24 lists Org-mode as "built-in".  That's the version
included in Emacs, not a package on elpa.gnu.org as I thought.

The "bleeding edge" package would be the only one there.


> I don't think it makes sense to use ELPA to re-distribute the version of
> Org-mode which users already have installed as part of their Emacs
> install.  Un-installing the bleeding edge Org-mode would be equivalent
> to downgrading to the Emacs version.

+1

> Also, I would tend to think that this would make the most sense if we
> automate the ELPA integration s.t. every time a new revision is pushed
> up the to git repository, the ELPA version is automatically upgraded
> (with a git commit hook).  If this isn't currently possible in ELPA then
> I'd agree with a point Jambunathan makes in this thread that this is a
> trick we can help ELPA to learn.
>
> The reason I think the above is important is that very frequently the
> answer to a question is "oh, I fixed that, please pull the latest from
> git", and we'll be constantly frustrating users if ELPA can't keep up
> with git.
>
> Best -- Eric



  Sebastian

Re: ELPA

[Achim Gratz]

"Eric Schulte" <schulte.eric@gmail.com> writes:
> I would think that it only makes sense to have one Org-mode package in
> ELPA, namely the bleeding edge git version of Org-mode.

I disagree and my vote is still on 'maint', i.e. what a user would be
most likely to install if he was visiting orgmode.org.  Master changes
too often and might have experimental commits that later get reversed.
For anybody not following the mailing list this would be exactly the
wrong version to get through ELPA, especially since ELPA (at least in
standard configuration) does not notify about new versions.

> ELPA serves as a way to distribute packages which are not (or can't
> be) part of Emacs,

This is true of the current ELPA (tromey.com), but I feel the GNU ELPA
might take on an additional role: 1) easily obtaining packages that
would not normally come with the standard install of Emacs and 2)
keeping users updated on packages that are still developed and change
between releases.  Org-mode would fall into the second category since it
will probably stay in the standard package set. 

> Also, I would tend to think that this would make the most sense if we
> automate the ELPA integration s.t. every time a new revision is pushed
> up the to git repository, the ELPA version is automatically upgraded
> (with a git commit hook).  If this isn't currently possible in ELPA then
> I'd agree with a point Jambunathan makes in this thread that this is a
> trick we can help ELPA to learn.

Again, Emacs24 ELPA will be able to query multiple archives, something
that current ELPA can't.  So Emacs24 will by default look at
elpa.gnu.org and users should be able to find the latest stable version
there (it may not show up exactly in the minute it is released on
orgmode.org).  It should then be easy enough to configure ELPA (from
org-mode even?) to look for updates on orgmode.org first and get
bleeding edge from there if the user asks to do this.  If GNU ELPA
adopts a different package update policy then both the stable and
bleeding edge version would need to be on orgmode.org -- has anybody had
a chance to ask or followed the discussion on the emacs.devel list?


Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptation for Waldorf microQ V2.22R2:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

Re: ELPA

[Richard Riley]

Achim Gratz <Stromeko@nexgo.de> writes:

> "Eric Schulte" <schulte.eric@gmail.com> writes:
>> I would think that it only makes sense to have one Org-mode package in
>> ELPA, namely the bleeding edge git version of Org-mode.
>
> I disagree and my vote is still on 'maint', i.e. what a user would be
> most likely to install if he was visiting orgmode.org.  Master changes
> too often and might have experimental commits that later get reversed.
> For anybody not following the mailing list this would be exactly the
> wrong version to get through ELPA, especially since ELPA (at least in
> standard configuration) does not notify about new versions.

I'd be interested to hear how many people actually use ELPA. I haunt the
#emacs channel a little bit and I know only a handful that use it. Is
the idea that it will be used more or central to emacs in the future?

Re: ELPA

[Scot Becker]

On Tue, Sep 28, 2010 at 6:48 PM, Eric Schulte <schulte.eric@gmail.com> wrote:
> I don't think it makes sense to use ELPA to re-distribute the version of
> Org-mode which users already have installed as part of their Emacs
> install.  Un-installing the bleeding edge Org-mode would be equivalent
> to downgrading to the Emacs version.

Sure that doesn't make sense, but remember that Emacs development
protocol is very conservative, and requires included packages to stop
all changes except bug fixes long in advance of new Emacs releases,
for stability.  This typically has had the result that an Emacs
version is released with an org-mode version which is a good few
org-mode releases behind---even on the day the Emacs release becomes
official.  In that case it would never happen that ELPA would be
re-distributing the version already installed with Emacs.  The latest
org-mode release will always be an advance on what got from a stock
Emacs.  This means that if you think that there is a place for people
to run the latest org release (as opposed to the dev version), then,
it seems, there is a decent place in ELPA for it, or?

Re: [PROPOSAL] Quick and easy installation instructions

[Carsten Dominik]

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


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.

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.

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

Re: [PROPOSAL] Quick and easy installation instructions

[Dan Davison]

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

Re: [PROPOSAL] Quick and easy installation instructions

[Carsten Dominik]

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

Re: Re: [PROPOSAL] Quick and easy installation instructions

[Giovanni Ridolfi]

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

> 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. 
>>>> [...]
>>>> 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 
>>>
>>> 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.
>>>
>>> Maybe we could actually have an Emacs command that will insert the
>>> basic stuff into .emacs 
>>> and optionally compile the Lisp files.

I disagree: the juice of speed (is Org-mode slow??) does not worth 
the squeeze of the problems arising from compilation:
+ different versions of Emacs that compile the files (!)
+ old .elc files left somewhere
+ the order of compilation (org.el is the *latest* file to be compiled
  [in my experience] so I had to compile twice)
+ the idle time & the disk usage during compilation

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

I disagree. Better a variable that can be customized (and default
compile:nil). 
If newbie want speed they shall read the Emacs manual and be able to
customize a variable. 

>> 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!
>
for the download part yes: contrib/org-track.el
not for editing .emacs.

Giovanni

Re: Re: [PROPOSAL] Quick and easy installation instructions

[Sebastian Rose]

Carsten Dominik <carsten.dominik@gmail.com> writes:
>>> 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!


It's in contrib/lisp/org-track.el.

But as Org mode is on ELPA already,

   M-x package-list-packages

and this kind of package handling is part of emacs-24 already, I guess
that's a better way to go?



  Sebastian

Re: Re: [PROPOSAL] Quick and easy installation instructions

[Dan Davison]

Sebastian Rose <sebastian_rose@gmx.de> writes:

> Carsten Dominik <carsten.dominik@gmail.com> writes:
>>>> 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!
>
>
> It's in contrib/lisp/org-track.el.
>
> But as Org mode is on ELPA already,

Great, I didn't know that. I'm not seeing it listed when I do M-x
package-list-packages. What do I need to do to see Org listed there?

Dan

>
>    M-x package-list-packages
>
> and this kind of package handling is part of emacs-24 already, I guess
> that's a better way to go?
>
>
>
>   Sebastian

Re: Re: [PROPOSAL] Quick and easy installation instructions

[Sebastian Rose]

Dan Davison <davison@stats.ox.ac.uk> writes:
> Sebastian Rose <sebastian_rose@gmx.de> writes:
>
>> Carsten Dominik <carsten.dominik@gmail.com> writes:
>>>>> 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!
>>
>>
>> It's in contrib/lisp/org-track.el.
>>
>> But as Org mode is on ELPA already,
>
> Great, I didn't know that. I'm not seeing it listed when I do M-x
> package-list-packages. What do I need to do to see Org listed there?
>
> Dan


You need emacs-24.1.  It comes with a modified version of package.el
that pulls from elpa.gnu.org.

Don't know if this requires extra work to provide Org mode packages on
both sites.  


Sebastian