worg-setup.org

   1 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   2 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   3 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   4 #+TITLE:      Worg setup on the http://orgmode.org server
   5 #+AUTHOR:     Worg people
   6 #+EMAIL:      mdl AT imapmail DOT org
   7 #+LANGUAGE:   en
   8 #+PRIORITIES: A C B
   9 #+CATEGORY:   worg
  10 #+OPTIONS:    H:3 num:nil toc:nil \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
  11
  12 * How Worg publishes itself as a website?
  13
  14   The server behind http://orgmode.org website takes care of publishing
  15   Worg into =HTML=.
  16
  17 ** How long does it take for a change to be published?
  18
  19    Export happens in two steps: the first step is to pull Worg
  20    repository on the server (this is cron'ed every 20 minutes, starting
  21    at 00:00), the second one is to publish the last version of Worg on
  22    the website (cron'ed every 20 minutes, starting at 00:10).
  23
  24    So for example, if you push a change in Worg at 00:37, this will be
  25    pulled on the server at 00:40 and will appear on the website at
  26    00:50.
  27
  28 ** There is a problem.  Can I check the export output?
  29
  30    The output of both cron jobs are readable here:
  31
  32    - http://orgmode.org/worg/pulling.txt
  33    - http://orgmode.org/worg/publishing.txt
  34
  35    Unmodified files are skipped during the process of exporting.
  36
  37 ** Looks like file XXX breaks the export.  What can I do?
  38
  39 1. Put this file in the FIXME directory at the root of the Worg
  40    repository.  Files in this FIXME directory won't be published.
  41
  42 2. Fix the page or contact the author of the page telling him about the
  43    problem.
  44
  45 ** Where are the "raw" .org files kept?
  46 In addition to publishing the html versions of the .org files Worg's
  47 git repository, the raw source .org files are also put in
  48 [[http://orgmode.org/worg/sources]]. It is nice to make the .org file
  49 available for those following a tutorial so that the actual .org
  50 file is viewable in addition to reading through the online html
  51 version. To do this, simply link to the file in the worg sources directory:
  52 - If the page in the git repository is =~/worg.git/path/to/file/file.org=,
  53 - Link like so: =http://orgmode.org/worg/sources/path/to/file/file.org=
  54
  55 * Are there any writing conventions?
  56
  57   Please don't use [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Specifying-File-Variables.html#Specifying-File-Variables][file variables]] in your org files.
  58
  59 * Can Worg execute code (via Babel)?
  60
  61   No.  The default automated export does not allow code execution on the
  62   server for obvious security reasons.
  63
  64   If you absolutely need code execution:
  65
  66   - double-check there is no issue when exporting this file locally
  67   - send [[mdl%20AT%20imapmail%20DOT%20org][me]] an email mentioning the file you want to export
  68   - I will double-check it myself and manually export it if it's okay
  69
  70 * What software is available on Worg for Babel code execution?
  71
  72   If babel code execution works on your machine, it doesn't mean it will
  73   work on the orgmode.org server.  Here is the list of available
  74   software on orgmode.org:
  75
  76   | Software     |                    Version |
  77   |--------------+----------------------------|
  78   | GNU Emacs    |                  23.1.90.1 |
  79   | shell        |                        3.1 |
  80   | R            |                     2.11.1 |
  81   | gnuplot-mode |                      O.6.0 |
  82   | gnuplot      |                        4.4 |
  83   | latex        | pdfeTeX 3.141592-1.21a-2.2 |
  84
  85 * What .emacs.el file is used on the server?
  86
  87 - http://orgmode.org/worg/sources/emacs.el
  88
  89 * I want it for my own server!
  90
  91   Here is the detailed recipe:
  92
  93   1. Configure your =~/.emacs.el= to know about your publishing projects
  94      (more information on publishing [[http://www.gnu.org/software/emacs/manual/html_node/org/Publishing.html][here]] and [[file:org-tutorials/org-publish-html-tutorial.org][here]])
  95
  96   2. Use =(setq org-export-htmlize-output-type 'css)= in ~/.emacs.el
  97
  98      (Do =C-h v org-export-htmlize-output-type= for more information
  99      about this.  Also =C-h v org-export-htmlize-generate-css= might
 100      help.)
 101
 102   3. Create =~/bin/pull-worg.sh= containing this script:
 103
 104      #+BEGIN_SRC sh-mode
 105      #!/bin/bash
 106
 107      # unless this is already done elsewhere:
 108      export PATH=$PATH:/home/you/bin/
 109
 110      # go to the place where you pull Worg
 111      cd /home/you/git/Worg/;
 112
 113      # pull Worg
 114      /home/you/bin/git-pull
 115      #+END_SRC
 116
 117   4. Create =~/bin/publish-worg.sh= containing this script:
 118
 119      #+BEGIN_SRC sh-mode
 120      #!/bin/bash
 121
 122      # Adapt it to point at your emacs executable
 123      /home/you/bin/emacs23 --batch -l ~/.emacs.el -f org-publish-all
 124      #+end_src
 125
 126   5. Cron the two scripts to run every hour, not at the same time
 127
 128      #+BEGIN_SRC generic-mode
 129      0 * * * * /home/you/bin/pull-worg.sh >> /dev/null 2>&1
 130      30 * * * * /home/you/bin/publish-worg.sh >> /dev/null 2>&1
 131      #+END_SRC
 132
 133   6. Sit and do something else while your Org repository is
 134      automagically exported to HTML