org-contrib/org-track.org

   1 #+TITLE:   org-track.el -- Keep current with Org-mode development: M-x org-track-update
   2 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:{} -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc author:nil
   3 #+STARTUP: odd
   4
   5 # This file is released by its authors and contributors under the GNU
   6 # Free Documentation license v1.3 or later, code examples are released
   7 # under the GNU General Public License v3 or later.
   8
   9 [[file:index.org][{Back to Worg's contibutions index}]]
  10
  11 *Note that this package might need to be updated to work with the new
  12 Org repo starting 2018. See [[http://lists.gnu.org/r/emacs-orgmode/2017-12/msg00578.html][here]] for the announcement.*
  13
  14 =org-track.el= aims to add a simple interface to track Org-mode's git
  15 repository on https://code.orgmode.org/bzg/org-mode.git. For non-git
  16 users, an =org-latest.tar.gz= archive is provided and will be downloaded
  17 from https://orgmode.org/org-latest.tar.gz.
  18
  19 The idea was born in a thread on the emacs-orgmode mailing list on [[https://orgmode.org/list/D5AB1A81-4B00-4B4F-9A1C-A2995AE297FA@nf.mpg.de][a
  20 request from Stefan Vollmar]].
  21
  22 If you run into trouble, drop us a mail on the [[mailto:emacs-orgmode@gnu.org][emacs-orgmode mailing
  23 list]].
  24
  25 # <<usage>>
  26
  27 * Usage
  28
  29   You will need an initial version of the Org-mode distribution in
  30   your load path:
  31
  32   #+begin_src emacs-lisp
  33     (add-to-list load-path "/path/to/org-mode/lisp")
  34     (require org)
  35     (require org-track)
  36   #+end_src
  37
  38   You will also need to clone the =org-contrib= repository from [[https://git.sr.ht/~bzg/org-contrib][here]],
  39   and to require =org-track=:
  40
  41   #+begin_src emacs-lisp
  42     (add-to-list load-path "/path/to/org-contrib/lisp")
  43     (require org-track)
  44   #+end_src
  45
  46   Adjust at least the variable =org-track-directory=. You can use
  47   customize for this:
  48
  49   : M-x customize-variable RET org-track-directory RET
  50
  51   From now on, to update and compile the current development version
  52   of Org-mode is just a matter of typing:
  53
  54   : M-x org-track-update RET
  55
  56   This will download the current =org-latest.tar.gz=, update the
  57   autoloads file =org-install.el= and (optionally) compile the sources.
  58
  59   /Note: This needs to be updated since org-install.el is obsolete./
  60
  61 # <<org-git-directory>>
  62 * org-track-directoy Layout
  63
  64   The =org-track-directory= is the only variable you'll need to
  65   adjust. This is the directory where your local copy of Org-mode will
  66   live. I.e., a sub directory 'org-mode/' will be added here. Also the
  67   file =org-latest.tar.gz= will be put here (and deleted after updates):
  68
  69   : org-track-directory
  70   :         |-- org-latest.tar.gz (if you download archives)
  71   :         `-- org-mode
  72   :             |-- ...
  73   :             |-- lisp          (add this dir to your loadpath)
  74   :             |-- contrib
  75   :             |   `-- lisp       (add this dir to your loadpath)
  76   :             `-- ...
  77
  78 * Fine-tuning
  79
  80   To see and/or change all the related variables, do:
  81
  82   : M-x customize-group RET org-track RET
  83
  84   Here is a list of all variables the script uses:
  85
  86   - =org-track-directory= :: The directory, where the sub-directory
  87     =org-mode/= lives. Default: =~/.emacs.d/org/lisp=
  88   - =org-track-compile-sources= :: Compile the sources after
  89     downloading? Defaults to =t=.
  90   - =org-track-org-url= :: The package is downloaded from this URL. This
  91     denotes the folder actually (i.e. the URL without the basename
  92     =org-latest.tar.gz=).
  93   - =org-track-org-package= :: The name the package itself. Default:
  94     =org-latest.tar.gz=.
  95   - =org-track-remove-package= :: Remove the downloaded package after
  96     unpacking?  The default is to keep the archive.
  97
  98 * How it works
  99
 100   The `*.tar.gz' version is extracted without external dependencies
 101   (tar-mode).  To make sure that =org-latest.tar.gz= is opened in
 102   tar-mode, the code modifies your `auto-mode-alist':
 103
 104   #+begin_src emacs-lisp
 105   (add-to-list 'auto-mode-alist '("org-latest\\.tar\\.gz\\'" . tar-mode))
 106   #+end_src
 107
 108   The downloaded package can be removed. See the option
 109   =org-git-remove-package=.  Default is not to remove =org-latest.tar.gz=.