diff --git a/doc/org.texi b/doc/org.texi index a2e6756ef..030eaf8dc 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -340,7 +340,7 @@ with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Introduction * Summary:: Brief summary of what Org does -* Installation:: How to install a downloaded version of Org +* Installation:: Installing Org * Activation:: How to activate Org for certain buffers * Feedback:: Bug reports, ideas, patches etc. * Conventions:: Typesetting conventions in the manual @@ -773,7 +773,7 @@ MobileOrg @menu * Summary:: Brief summary of what Org does -* Installation:: How to install a downloaded version of Org +* Installation:: Installing Org * Activation:: How to activate Org for certain buffers * Feedback:: Bug reports, ideas, patches etc. * Conventions:: Typesetting conventions in the manual @@ -853,118 +853,69 @@ Theory Ltd.} @cindex installation @cindex XEmacs -@b{Important:} @i{If you the version of Org that comes with Emacs or as a -XEmacs package, please skip this section and go directly to @ref{Activation}. -If you downloaded Org as an ELPA package, please read the instructions on the -@uref{http://orgmode.org/elpa.html, Org ELPA page}. To see what version of Org -(if any) is part of your Emacs distribution, type @kbd{M-x org-version} (if -your Emacs distribution does not come with Org, this function will not be -defined).} - -Installation of Org mode uses a build system, which is described in more -detail on @uref{http://orgmode.org/worg/dev/org-build-system.html, Worg}. - -If you have downloaded Org from the Web as a distribution @file{.zip} or -@file{.tar.gz} archive, take the following steps to install it: +Org is part of recent distributions of GNU Emacs, so you normally don't need +to install it. If, for one reason or another, you want to install Org on top +of this pre-packaged version, there are three ways to do it: @itemize @bullet -@item Unpack the distribution archive. -@item Change into (@code{cd}) the Org directory. -@item Run @code{make help config} -and then check and edit the file @file{local.mk} if the default configuration -does not match your system. Set the name of the Emacs binary (likely either -@file{emacs} or @file{xemacs}), and the paths to the directories where local -Lisp and Info files will be installed. If the Emacs binary is not in your -path, give the full path to the executable. Avoid spaces in any path names. -@item Run @code{make config} -again to check the configuration. -@item Run @code{make install} or @code{sudo make install} -to build and install Org mode on your system. +@item By using Emacs package system. +@item By downloading Org as an archive. +@item By using Org's git repository. @end itemize -If you use a cloned Git repository, then the procedure is slightly different. -The following description assumes that you are using the @code{master} branch -(where the development is done). You could also use the @code{maint} branch -instead, where the release versions are published, just replace @code{master} -with @code{maint} in the description below. +We @b{strongly recommend} to stick to a single installation method. -@itemize @bullet -@item Change into (@code{cd}) the Org repository. -@item Run @code{git checkout master} -to switch to the @code{master} branch of the Org repository. -@item Run @code{make help} -and then check and edit the file @file{local.mk}. You must set the name of -the Emacs binary (likely either @file{emacs} or @file{xemacs}), and the paths -to the directories where local Lisp and Info files will be installed. If the -Emacs binary is not in your path, you must give the full path to the -executable. Avoid spaces in any path names. -@item Run @code{make config} -to check the configuration. -@item Optionally run @code{make test} -to build Org mode and then run the full testsuite. -@item Run @code{make update2} or @code{make up2} -to update the Git repository and build and install Org mode. The latter -invocation runs the complete test suite before installation and installs only -if the build passes all tests. -@end itemize +@subsubheading Using Emacs packaging system -If you don't have access to the system-wide directories and you don't want to -install somewhere into your home directory, you can run Org directly from the -distribution directory or Org repository by compiling Org mode in place: +Recent Emacs distributions include a packaging system which lets you install +Elisp libraries. You can install Org with @kbd{M-x package-install RET org}. +To make sure your Org configuration is well taken into account, initialize +the package system with @code{(package-initialize)} before setting any Org +option. If you want to use Org's package repository, check out the +@uref{http://orgmode.org/elpa.html, Org ELPA page}. -@itemize @bullet -@item Change into (@code{cd}) the Org repository. -@item Run @code{git checkout master} -to switch to the @code{master} branch of the Org repository. -@item Run @code{make compile} -@end itemize +@subsubheading Downloading Org as an archive -Last but not least you can also run Org mode directly from an Org repository -without any compilation. Simply replace the last step in the recipe above -with @code{make uncompiled}. - -Then add the following line to @file{.emacs}: +You can download Org latest release from @uref{http://orgmode.org/, Org's +website}. In this case, make sure you set the load-path correctly in your +@file{.emacs}: @example (add-to-list 'load-path "~/path/to/orgdir/lisp") @end example -@noindent -If you plan to use code from the @file{contrib} subdirectory without -compiling them, do a similar step for this directory: +The downloaded archive contains contributed libraries that are not included +in Emacs. If you want to use them, add the @file{contrib} directory to your +load-path: @example (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t) @end example -If you want to include those files with the build and install, please -customize the variable @code{ORG_ADD_CONTRIB} instead in your @code{local.mk} -file, for more details please see this -@uref{http://orgmode.org/worg/dev/org-build-system.html#sec-4-1-2, -description on Worg}. +Optionally, you can compile the files and/or install them in your system. +Run @code{make help} to list compilation and installation options. -Installing Info files is system dependent, because of differences in the -@file{install-info} program. The Info documentation is installed together -with the rest of Org mode. If you don't install Org mode, it is possible to -install the Info documentation separately (you need to have -install-info@footnote{The output from install-info (if any) is system -dependent. In particular Debian and its derivatives use two different -versions of install-info and you may see the message: +@subsubheading Using Org's git repository + +You can clone Org's repository and install Org like this: @example -This is not dpkg install-info anymore, but GNU install-info -See the man page for ginstall-info for command line arguments +$ cd ~/src/ +$ git clone git://orgmode.org/org-mode.git +$ make autoloads @end example -@noindent which can be safely ignored.} -on your system). +Note that @code{make autoloads} is mandatory: it defines Org's version and +Org's autoloaded functions, respectively in @file{org-version.el} and in +@file{org-loaddefs.el}. -@example -make install-info -@end example +Remember to add the correct load-path as described in the method above. -Do not forget to activate Org as described in the following section. -@page +You can also compile and install Org from this git repository: check +@code{make help} to get the list of compilation/installation options. + +For more detailed explanations on Org's build system, please check the Org +Build System page on @uref{http://orgmode.org/worg/dev/org-build-system.html, Worg}. @node Activation, Feedback, Installation, Introduction @section Activation