worg-setup.org

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