Meaning of install

Meaning of install

[Thomas S. Dye]

Aloha all,

Section 1.2 of the Org manual in git is called `Installation', and it
includes instructions on three ways `to install Org on top' of the Org
that ships with Emacs.

Near the bottom of that page, after giving instructions on how to
install Org from the git repository, it says that "You can also ...
install Org with `make install'."

This is confusing to a User like me.  After having been given
instructions on how to install Org:

     $ cd ~/src/
     $ git clone git://orgmode.org/org-mode.git
     $ make autoloads

I now find that I can also install with `make install.'

It seems clear to me that `install' is being used in two different senses
here.  I'd like to disambiguate--can someone suggest a concise way to do
this?

Thanks,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: Meaning of install

[Yagnesh Raghava Yakkala]

Hello Thomas,

On Mar 13 2013, tsd@tsdye.com (Thomas S. Dye) wrote:

>      $ cd ~/src/
>      $ git clone git://orgmode.org/org-mode.git
>      $ make autoloads

If user decides to stop at this point he needs to add set paths in
`.emacs'.

> I now find that I can also install with `make install.'

Here `make install' installs compiled org into emacs' site-lisp directory, in
which case there is no need to set paths in `.emacs'.

Thanks.,
-- 
ఎందరో మహానుభావులు అందరికి వందనములు.
YYR

Re: Meaning of install

[Achim Gratz]

Thomas S. Dye writes:
> Section 1.2 of the Org manual in git is called `Installation', and it
> includes instructions on three ways `to install Org on top' of the Org
> that ships with Emacs.
>
> Near the bottom of that page, after giving instructions on how to
> install Org from the git repository, it says that "You can also ...
> install Org with `make install'."
>
> This is confusing to a User like me.  After having been given
> instructions on how to install Org:
>
>      $ cd ~/src/
>      $ git clone git://orgmode.org/org-mode.git
>      $ make autoloads
>
> I now find that I can also install with `make install.'

Make a suggestion.  When the new build system went live I had adapted
the description with explicit instructions for each installation method,
which was later simplified (a touch too much for my tastes) by Bastien —
which is what you look at now.  It actually doesn't even work as
documented, I see now.

> It seems clear to me that `install' is being used in two different senses
> here.  I'd like to disambiguate--can someone suggest a concise way to do
> this?

Using Org from Git can be done in two fundamentally different ways:

 a) using the worktree directly as your installation,

 b) using it as the source for an installation in a different place.

Installation is used here in the sense that your Emacs runs the
"installed" code.


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

SD adaptation for Waldorf rackAttack V1.04R1:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

Re: Meaning of install

[Thomas S. Dye]

Aloha Achim and Yagnesh Raghava Yakkala,

Achim Gratz <Stromeko@nexgo.de> writes:

>> It seems clear to me that `install' is being used in two different senses
>> here.  I'd like to disambiguate--can someone suggest a concise way to do
>> this?
>
> Using Org from Git can be done in two fundamentally different ways:
>
>  a) using the worktree directly as your installation,
>
>  b) using it as the source for an installation in a different place.
>
> Installation is used here in the sense that your Emacs runs the
> "installed" code.

Yes, I think this structure needs to be reflected more clearly in the
manual.  I'll propose some new language when I get back to this.

In the meantime, one more question. What are the considerations for the
location of the worktree? If possible, I think it would be a good idea
for the manual to make a recommendation for the worktree location and
also provide a suitable warning about where *not* to put the worktree,
if needed.

Thanks for your help.

Tom
-- 
Thomas S. Dye
http://www.tsdye.com

Re: Meaning of install

[Achim Gratz]

Thomas S. Dye writes:
> Yes, I think this structure needs to be reflected more clearly in the
> manual.  I'll propose some new language when I get back to this.

Please go back in time and look at the earlier version(s).  I think
there may be some middle ground between what we have now and what we had
then.  All in all I'd think that it would be enough to tell people how
to install from ELPA and from Git (the "full install" version) and send
them to Worg for all the other possibilities.

> In the meantime, one more question. What are the considerations for the
> location of the worktree? If possible, I think it would be a good idea
> for the manual to make a recommendation for the worktree location and
> also provide a suitable warning about where *not* to put the worktree,
> if needed.

Whereever you find it convenient, which is somewhere in your home
directory most likely.  About the only place you should not put it is
inside Emacs' own directory tree.


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

Wavetables for the Terratec KOMPLEXER:
http://Synth.Stromeko.net/Downloads.html#KomplexerWaves

Re: Meaning of install

[Nick Dokos]

Thomas S. Dye <tsd@tsdye.com> wrote:

> Aloha Achim and Yagnesh Raghava Yakkala,
> 
> Achim Gratz <Stromeko@nexgo.de> writes:
> 
> >> It seems clear to me that `install' is being used in two different senses
> >> here.  I'd like to disambiguate--can someone suggest a concise way to do
> >> this?
> >
> > Using Org from Git can be done in two fundamentally different ways:
> >
> >  a) using the worktree directly as your installation,
> >
> >  b) using it as the source for an installation in a different place.
> >
> > Installation is used here in the sense that your Emacs runs the
> > "installed" code.
> 
> Yes, I think this structure needs to be reflected more clearly in the
> manual.  I'll propose some new language when I get back to this.
> 

Now that it's available, the "make install" method should probably be
described first in the documentation as the preferred method: it is
appropriate for the great majority of cases (Achim would probably say
"all cases").

Using the worktree is for diehard tinkerers, or old farts like me who
did it this way long before there was a build system and now don't want
to change our ossified ways.

> In the meantime, one more question. What are the considerations for the
> location of the worktree? If possible, I think it would be a good idea
> for the manual to make a recommendation for the worktree location and
> also provide a suitable warning about where *not* to put the worktree,
> if needed.
> 

Like *any* worktree, It should be under one's home directory.

Nick

Re: Meaning of install

[Thomas S. Dye]

Hi Nick, Achim, and Yagnesh Raghava Yakkala,

How is this?

1.2.3 Use the Org git repository
--------------------------------

You can clone the development version from the Org git repository,
typically to a location under your home directory.  The following
example assumes this location is `src/' in your home directory:

$ cd ~/src/
$ git clone git://orgmode.org/org-mode.git

   In most cases, you will probably want to run `make install' to
install Org with the Emacs system files.  Please run `make help' to get
the full list of options.

   If, for some reason, you would like to run Org from the clone
location, remember to set the load-path correctly in your `.emacs'.
Continuing from the previous example:

(add-to-list 'load-path "~/src/org-mode/lisp")

   Note that in this case, `make autoloads' is mandatory: it defines
Org's version in `org-version.el' and Org's autoloads in
`org-loaddefs.el'.  Continuing from the example:

$ cd org-mode
$ make autoloads

   You can also compile with `make', generate the documentation with
`make doc', or create a local configuration with `make config'.

   A detailed explanation of Org's build system can be found at the Org
Build System page on Worg
(http://orgmode.org/worg/dev/org-build-system.html).


All the best,
Tom
-- 
Thomas S. Dye
http://www.tsdye.com

Re: Meaning of install

[Achim Gratz]

Thomas S. Dye writes:
>
> $ cd ~/src/
> $ git clone git://orgmode.org/org-mode.git
> $ cd org-mode

Move the cd up here.

>    In most cases, you will probably want to run `make install' to
> install Org with the Emacs system files.  Please run `make help' to get
> the full list of options.

See, that's one of those short descriptions that only seem clear, but
aren't actually helpful.  You can't "make install" just now, you have to
decide Whether and where to install and adapt the local configuration
accordingly, both for the build system and within Emacs.  The default
local config requires that you can install into system locations and it
only works OOTB on GNU systems.

>    You can also compile with `make', generate the documentation with
> `make doc', or create a local configuration with `make config'.

If no local configuration exists, the first invocation of make will
create a default one.  Make config will display the local configuration.


Regards,
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: Meaning of install

[Andreas Röhler]

Am 13.03.2013 08:19, schrieb Achim Gratz:
> Thomas S. Dye writes:
>>
>> $ cd ~/src/
>> $ git clone git://orgmode.org/org-mode.git
>> $ cd org-mode
>
> Move the cd up here.
>
>>     In most cases, you will probably want to run `make install' to
>> install Org with the Emacs system files.  Please run `make help' to get
>> the full list of options.
>
> See, that's one of those short descriptions that only seem clear, but
> aren't actually helpful.  You can't "make install" just now, you have to
> decide Whether and where to install and adapt the local configuration
> accordingly, both for the build system and within Emacs.  The default
> local config requires that you can install into system locations and it
> only works OOTB on GNU systems.
>
>>     You can also compile with `make', generate the documentation with
>> `make doc', or create a local configuration with `make config'.
>
> If no local configuration exists, the first invocation of make will
> create a default one.  Make config will display the local configuration.
>
>
> Regards,
> Achim.
>

BTW would welcome some hints how to proceed when bug-fixing, extending etc. I.e.
installing that stuff right on probably isn't preferable.

Trying to load it from the git-repo, not sure it that works correctly.

Thanks,

Andreas

Re: Meaning of install

[Yagnesh Raghava Yakkala]

Hello Achim, Thomas,

On Mar 13 2013, Achim Gratz <Stromeko@nexgo.de> wrote:

> Thomas S. Dye writes:
>>
>> $ cd ~/src/
>> $ git clone git://orgmode.org/org-mode.git
>> $ cd org-mode
>
> Move the cd up here.
>
>>    In most cases, you will probably want to run `make install' to
>> install Org with the Emacs system files.  Please run `make help' to get
>> the full list of options.
>
> See, that's one of those short descriptions that only seem clear, but
> aren't actually helpful.  You can't "make install" just now, you have to
> decide Whether and where to install and adapt the local configuration
> accordingly, both for the build system and within Emacs.  

I use el-get to manage my org installation from git repo. el-get simply calls
'make oldorg' and sets path.  So may be we can mention about oldorg target for
users who want to load Org from git repository, and for users who wants to
install, we can point to documentation of build system on worg.

Thanks.,
-- 
ఎందరో మహానుభావులు అందరికి వందనములు.
YYR

Re: Meaning of install

[Bastien]

Hi Andreas,

Andreas Röhler <andreas.roehler@easy-emacs.de> writes:

> BTW would welcome some hints how to proceed when bug-fixing, extending etc. I.e.
> installing that stuff right on probably isn't preferable.

Can you be more specific?  What information do you want, where do
you search for it, what did you find, what did you not find?

There is a lot of information on Worg, which is open to contributions.

> Trying to load it from the git-repo, not sure it that works correctly.

Well, we can't really help you with so little information :/

-- 
 Bastien

Re: Meaning of install

[Bastien]

Hi Thomas,

thanks for looking into it!  I think the installation instructions in
the manual should be minimalistic but I surely made them too terse.
So any enhancement here is welcome, and now is the right time.

Best,

-- 
 Bastien

Re: Meaning of install

[Andreas Röhler]

Am 13.03.2013 09:43, schrieb Bastien:
> Hi Andreas,
>
> Andreas Röhler <andreas.roehler@easy-emacs.de> writes:
>
>> BTW would welcome some hints how to proceed when bug-fixing, extending etc. I.e.
>> installing that stuff right on probably isn't preferable.
>
> Can you be more specific?  What information do you want, where do
> you search for it, what did you find, what did you not find?
>
> There is a lot of information on Worg, which is open to contributions.
>
>> Trying to load it from the git-repo, not sure it that works correctly.
>
> Well, we can't really help you with so little information :/
>

Find the http://orgmode.org/worg/dev/index.html, that's good :)

http://orgmode.org/worg/doc.html helpful in general, okay.

But how to setup up a developing environment?

http://orgmode.org/worg/dev/org-build-system.html tells

Org can be run directly from sources,...

that's all I see here.

However, loading the sources seems to have some edges.
At least didn't arrive to do it in a reliable, predictable way,
i.e. after loading several files explicitely, tests show different result.

Derive from that, load was not complete.

Any recommendation which make commands to run here?

Thanks,

Andreas

Re: Meaning of install

[Bastien]

Andreas Röhler <andreas.roehler@easy-emacs.de> writes:

> Any recommendation which make commands to run here?

~$ make helpall

:)

-- 
 Bastien

Re: Meaning of install

[Thomas S. Dye]

Aloha all,

Thanks for your help and patience as I try to find the simplest, most
widely applicable, path to a successful Org installation.

I've decided not to mention el-get in the manual.  It looks like a great
power-user tool, but I don't think it fits here.  Perhaps something on
Worg (if it's not already there)?

Here is the most recent version:

1.2.3 Use the Org git repository
--------------------------------

You can clone the development version of the Org git repository,
typically to a location under your home directory.  The example in this
section assumes this location is `src/' in your home directory:

$ cd ~/src/
$ git clone git://orgmode.org/org-mode.git
$ cd org-mode

   In most cases where you have permission to write to system locations,
you will probably want to install Org with the Emacs system files.
This is a system-specific operation that is guided by a file,
`local.mk', which you must ensure is configured properly.  First,
generate a `local.mk' template with the command `make local.mk'.  Edit
`local.mk' following the instructions in the file, and save it.(1)
Finally, run `make install' to build all of Org and install it.  The
command `make help' provides a full list of options for the build
system.

   If you would like to run Org from the clone location, instead of
installing it with the Emacs system files, you can simply run `make
autoloads' and set the load-path in your `.emacs'.  Using the example
location, add this to `.emacs':

(add-to-list 'load-path "~/src/org-mode/lisp")

   If your installation has special requirements, please refer to the
detailed description of the capable build system at the Org Build
System page (http://orgmode.org/worg/dev/org-build-system.html).

   ---------- Footnotes ----------

   (1) The `local.mk' template is designed to work out of the box with
GNU systems.

All the best,
Tom
-- 
Thomas S. Dye
http://www.tsdye.com

Re: Meaning of install

[Bastien]

Hi Thomas,

tsd@tsdye.com (Thomas S. Dye) writes:

> Thanks for your help and patience as I try to find the simplest, most
> widely applicable, path to a successful Org installation.

Thanks for this, I think these explanations are better articulated
than the ones in the manual.  

Let's get the "go!" from Achim and commit this change in the manual.

> I've decided not to mention el-get in the manual.  It looks like a great
> power-user tool, but I don't think it fits here.  Perhaps something on
> Worg (if it's not already there)?

Mentioning el-get on Worg is fine IMO.

Best,

-- 
 Bastien

Re: Meaning of install

[Achim Gratz]

Thomas S. Dye writes:
> Thanks for your help and patience as I try to find the simplest, most
> widely applicable, path to a successful Org installation.

I especially like the fact that it didn't get longer than before.

>    In most cases where you have permission to write to system locations,
> you will probably want to install Org with the Emacs system files.
> This is a system-specific operation that is guided by a file,
> `local.mk', which you must ensure is configured properly.  First,
> generate a `local.mk' template with the command `make local.mk'.  Edit
> `local.mk' following the instructions in the file, and save it.(1)

I would mention "make config" here for a sanity check of the created
configuration.



Regards,
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: Meaning of install

[Thomas S. Dye]

Aloha Achim,

Achim Gratz <Stromeko@nexgo.de> writes:

> Thomas S. Dye writes:

>>    In most cases where you have permission to write to system locations,
>> you will probably want to install Org with the Emacs system files.
>> This is a system-specific operation that is guided by a file,
>> `local.mk', which you must ensure is configured properly.  First,
>> generate a `local.mk' template with the command `make local.mk'.  Edit
>> `local.mk' following the instructions in the file, and save it.(1)
>
> I would mention "make config" here for a sanity check of the created
> configuration.

Good idea.  Done.  Thanks!

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: Meaning of install

[Andreas Röhler]

Am 13.03.2013 12:56, schrieb Bastien:
> Andreas Röhler <andreas.roehler@easy-emacs.de> writes:
>
>> Any recommendation which make commands to run here?
>
> ~$ make helpall
>
> :)
>

Another great piece, thanks!

Re: Meaning of install

[Bastien]

Hi Thomas,

tsd@tsdye.com (Thomas S. Dye) writes:

>> I would mention "make config" here for a sanity check of the created
>> configuration.
>
> Good idea.  Done.

Oh, I thought it was done in Org's org.texi manual but I understand
this is done in orgmanual.git, right?

Could you make the change in org.texi too?

Thanks!

-- 
 Bastien

Re: Meaning of install

[Thomas S. Dye]

Hi Bastien,

Bastien <bzg@altern.org> writes:

> Hi Thomas,
>
> tsd@tsdye.com (Thomas S. Dye) writes:
>
>>> I would mention "make config" here for a sanity check of the created
>>> configuration.
>>
>> Good idea.  Done.
>
> Oh, I thought it was done in Org's org.texi manual but I understand
> this is done in orgmanual.git, right?

Yes, that's right. I'm bringing orgmanual.git up-to-date using the git
diff magic formula you sent me a week and a half ago and making some
edits as I go along. Changes to the installation section began as minor
edits, but grew as this thread went on.

> Could you make the change in org.texi too?

You have the persistence of a good maintainer. I haven't finished
editing the other installation sections, so I'm not in a position to
repeat my earlier reply to a similar query, which was to export
orgmanual! :)

I do hope it will be possible in the near future for me to take a larger
role in maintaining the Org manual. That is my goal. But for me to do
that the manual will need to be in Org, not texi. For purely personal
reasons that don't reflect at all on the Org community or the manual,
org.texi fills me with horror. If the orgmanual experiment fails then I
plan to beat a hasty retreat, lick my wounds, and work happily on other
interesting tasks at hand.

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com