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