本文翻譯自 http://doc.norang.ca/org-mode.html ，原文作者為Bernt Hansen 。由于原文較長，是以會分多篇文章來釋出。轉載請标記出處。
本章主要介紹org釋出導出功能，org-mode雖然是文本方式，但是提供了強大的釋出導出功能，友善導出到很多格式文檔，包含
HTML，LaTex，Markdown等。
1 釋出導出章節
我平時不會對我任務做很多釋出相關的操作，但是我保留了些敏感的客戶系統資訊。大部分都是通過備忘形式 記錄并導出到HTML中。
目前 http://doc.norang.ca/ 網站所有網頁都是通過我的org檔案釋出生成的。這包含網站的索引頁面。
org-mode可以将檔案釋出為很多格式，包含（但不限于）
- ASCII (文本 - 并非org格式檔案)
- HTML
- LaTeX
-
Docbook
這可以導出成大量其他格式，像 ODF，XML等
-
PDF
通過LaTex以及Docbook
- iCal
我沒有花精力去研究org-mode布局功能（使得文檔更美觀）。對于釋出，我主要使用釋出場景是用org-mode建立些HTML文檔，友善線上閱讀。也許将來因為需要，我會研究下org布局功能。
1.1 新的導出設定
新的導出功能由 Nicolas Goazious實作并在org 8.0版本中釋出。
我的導出設定如下：
字母清單選項需要在導出設定被載入後才能正确工作。
(setq org-alphabetical-lists t)
;; Explicitly load required exporters
(require 'ox-html)
(require 'ox-latex)
(require 'ox-ascii)
1.1.1 老的exporter轉換成新的exporter
下面是我做的為相容新的exporter功能的修改。
- exporters 顯示依賴
- 添加
ox-html
- 添加
ox-latex
- 添加
ox-ascii
- 添加
- 重命名參數
-
org-export-html-style-extra
org-html-head-extra
-
org-export-html-validation-link
org-html-validation-link
-
org-export-html-inline-images
org-html-inline-images
-
org-export-html-style-include-default
org-html-head-include-default-style
-
org-export-html-xml-declaration
org-html-xml-declaration
-
org-export-latex-listings
org-latex-listings
-
org-export-html-style-include-scripts
org-html-head-include-scripts
-
- 釋出修改
-
org-publish-org-to-html
org-html-publish-to-html
-
org-publish-org-to-org
org-org-publish-to-org
- 重命名
:publishing-function
-
:style
:html-head
-
- 修改
bh/is-late-deadline
-
根據截止日期反轉agenda清單
負值将不會在agenda中顯示
- 添加空行防止被導出。
1.2 org-babel 設定
org-babel使得org檔案通過使用外部插件，比如ditaa, graphviz, PlantUML等其他工具來生成各種圖示。
設定非常簡單。
ditaa
是跟随org-mode釋出。對于其他插件，你需要在系統中安裝
graphviz
以及
PlantUML
軟體包。
(setq org-ditaa-jar-path "~/git/org-mode/contrib/scripts/ditaa.jar")
(setq org-plantuml-jar-path "~/java/plantuml.jar")
(add-hook 'org-babel-after-execute-hook 'bh/display-inline-images 'append)
; Make babel results blocks lowercase
(setq org-babel-results-keyword "results")
(defun bh/display-inline-images ()
(condition-case nil
(org-display-inline-images)
(error nil)))
(org-babel-do-load-languages
(quote org-babel-load-languages)
(quote ((emacs-lisp . t)
(dot . t)
(ditaa . t)
(R . t)
(python . t)
(ruby . t)
(gnuplot . t)
(clojure . t)
(sh . t)
(ledger . t)
(org . t)
(plantuml . t)
(latex . t))))
; Do not prompt to confirm evaluation
; This may be dangerous - make sure you understand the consequences
; of setting this -- see the docstring for details
(setq org-confirm-babel-evaluate nil)
; Use fundamental mode when editing plantuml blocks with C-c '
(add-to-list 'org-src-lang-modes (quote ("plantuml" . fundamental)))
然後你隻需要建立一個
begin-src
塊為合适的工具，編輯檔案，通過快捷鍵
C-c C-c
生成圖檔。然後結構就會顯示。你可以通過
C-c C-x C-v
來控制圖像顯示與否。
我禁止啟動時候，在org檔案加載圖像因為當我通過ssh來登入遠端打開org檔案，如果預設顯示圖檔就會有問題 （比如說我的android手機）在非X系統上沒法顯示圖檔。
對我來說能夠遠端登入并檢視org 檔案比遠端檢視圖像更加重要。
;; Don't enable this because it breaks access to emacs from my Android phone
(setq org-startup-with-inline-images nil)
1.3 如何使用ditta
ditaa 是一個能夠快速将想法轉換成圖像的工具， 并且
ditaa
是跟着 org-mode一起釋出的！本文檔中的所有圖檔都是通過org-mode使用純文字方式自動生成的。
Artist模式友善使用ditaa建立方塊以及連線。
ditaa在org-mode畫圖的源碼像下面這樣：
#+begin_src ditaa :file some_filename.png :cmdline -r -s 0.8
<context of ditaa source goes here>
#+end_src
下面是沒有
#+begin_src
以及
#+end_src
畫出的圖形的例子。
+-----------+ +---------+
| PLC | | |
| Network +<------>+ PLC +<---=---------+
| cRED | | c707 | |
+-----------+ +----+----+ |
^ |
| |
| +----------------|-----------------+
| | | |
v v v v
+----------+ +----+--+--+ +-------+---+ +-----+-----+ Windows clients
| | | | | | | | +----+ +----+
| Database +<----->+ Shared +<---->+ Executive +<-=-->+ Operator +<---->|cYEL| . . .|cYEL|
| c707 | | Memory | | c707 | | Server | | | | |
+--+----+--+ |{d} cGRE | +------+----+ | c707 | +----+ +----+
^ ^ +----------+ ^ +-------+---+
| | |
| +--------=--------------------------+
v
+--------+--------+
| |
| Millwide System | -------- Data ---------
| cBLU | --=----- Signals ---=--
+-----------------+
1.4 使用graphviz
Graphviz 是另一個偉大的友善在org文檔畫圖的工具。
graphviz在org中畫圖源碼看上去如下：
#+begin_src dot :file some_filename.png :cmdline -Kdot -Tpng
<context of graphviz source goes here>
#+end_src
digraph G {
size="8,6"
ratio=expand
edge [dir=both]
plcnet [shape=box, label="PLC Network"]
subgraph cluster_wrapline {
label="Wrapline Control System"
color=purple
subgraph {
rank=same
exec
sharedmem [style=filled, fillcolor=lightgrey, shape=box]
}
edge[style=dotted, dir=none]
exec -> opserver
exec -> db
plc -> exec
edge [style=line, dir=both]
exec -> sharedmem
sharedmem -> db
plc -> sharedmem
sharedmem -> opserver
}
plcnet -> plc [constraint=false]
millwide [shape=box, label="Millwide System"]
db -> millwide
subgraph cluster_opclients {
color=blue
label="Operator Clients"
rankdir=LR
labelloc=b
node[label=client]
opserver -> client1
opserver -> client2
opserver -> client3
}
}
-Kdot
是可選的（預設是
dot
）但是你可以用其他graphviz來替換(例如
twopi
,
neato
,
circo
等)。
1.5 使用PlantUML
我剛開始使用PlantUML，它是基于Graphviz建立的。我現在仍在嘗試使用它，到現在為止我太喜歡它了。本文中狀态圖都是通過PlantUML來畫的。
PlantUML在org中繪圖源碼看上去如下：
#+begin_src plantuml :file somefile.png
<context of PlantUML source goes here>
#+end_src
1.5.1 時序圖
title Example Sequence Diagram
activate Client
Client -> Server: Session Initiation
note right: Client requests new session
activate Server
Client <-- Server: Authorization Request
note left: Server requires authentication
Client -> Server: Authorization Response
note right: Client provides authentication details
Server --> Client: Session Token
note left: Session established
deactivate Server
Client -> Client: Saves token
deactivate Client
1.5.2 用例圖
LabUser --> (Runs Simulation)
LabUser --> (Analyses Results)
1.5.3 對象圖
Object1 <|-- Object2
Object1 : someVar
Object1 : execute()
Object2 : getState()
Object2 : setState()
Object2 : state
1.5.4 狀态圖
[*] --> Start
Start -> State2
State2 -> State3
note right of State3: Notes can be\nattached to states
State2 --> State4
State4 -> Finish
State3 --> Finish
Finish --> [*]
1.6 釋出單個檔案
org-mode通過一個導出函數, 就可以将該檔案導出成一個标準的格式的檔案。導出函數一般綁定到快捷鍵
C-c C-e
，之後跟着導出類型的快捷鍵就可以完成導出。
通過這種方式可以将單個檔案以及檔案的一部分導出–如果限制org-mode檔案到檔案的部分内容， 當導出的時候隻會導出選擇部分。
1.7 釋出項目
我使用publishing功能來導出多個檔案或者項目。我不想記住導出檔案生成的位置， org-mode項目可以解決這個問題。
http://doc.norang.ca 這個網站（其他一些非公開的檔案）都是通過org-mode檔案 來建立，通過項目形式釋出。象我這樣，隻配置一次，後面就不再注意這些細節的人這個功能非常棒。我喜歡這種工作方式(tm).
目前，我有如下5個項目，通過org-mode釋出：
- norang （網站）
- doc.norang.ca (網站，釋出文檔）
- doc.norang.ca/privat (網站，非公開完檔）
- www.norang.ca/tmp (用測試org-mode來臨時釋出網站）
- org檔案（其他網站使用的org檔案）
如下是我的設定：
; experimenting with docbook exports - not finished
(setq org-export-docbook-xsl-fo-proc-command "fop %s %s")
(setq org-export-docbook-xslt-proc-command "xsltproc --output %s /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl %s")
;
; Inline images in HTML instead of producting links to the image
(setq org-html-inline-images t)
; Do not use sub or superscripts - I currently don't need this functionality in my documents
(setq org-export-with-sub-superscripts nil)
; Use org.css from the norang website for export document stylesheets
(setq org-html-head-extra "<link rel=\"stylesheet\" href=\"http://doc.norang.ca/org.css\" type=\"text/css\" />")
(setq org-html-head-include-default-style nil)
; Do not generate internal css formatting for HTML exports
(setq org-export-htmlize-output-type (quote css))
; Export with LaTeX fragments
(setq org-export-with-LaTeX-fragments t)
; Increase default number of headings to export
(setq org-export-headline-levels 6)
; List of projects
; norang - http://www.norang.ca/
; doc - http://doc.norang.ca/
; org-mode-doc - http://doc.norang.ca/org-mode.html and associated files
; org - miscellaneous todo lists for publishing
(setq org-publish-project-alist
;
; http://www.norang.ca/ (norang website)
; norang-org are the org-files that generate the content
; norang-extra are images and css files that need to be included
; norang is the top-level project that gets published
(quote (("norang-org"
:base-directory "~/git/www.norang.ca"
:publishing-directory "/ssh:[email protected]:~/www.norang.ca/htdocs"
:recursive t
:table-of-contents nil
:base-extension "org"
:publishing-function org-html-publish-to-html
:style-include-default nil
:section-numbers nil
:table-of-contents nil
:html-head "<link rel=\"stylesheet\" href=\"norang.css\" type=\"text/css\" />"
:author-info nil
:creator-info nil)
("norang-extra"
:base-directory "~/git/www.norang.ca/"
:publishing-directory "/ssh:[email protected]:~/www.norang.ca/htdocs"
:base-extension "css\\|pdf\\|png\\|jpg\\|gif"
:publishing-function org-publish-attachment
:recursive t
:author nil)
("norang"
:components ("norang-org" "norang-extra"))
;
; http://doc.norang.ca/ (norang website)
; doc-org are the org-files that generate the content
; doc-extra are images and css files that need to be included
; doc is the top-level project that gets published
("doc-org"
:base-directory "~/git/doc.norang.ca/"
:publishing-directory "/ssh:[email protected]:~/doc.norang.ca/htdocs"
:recursive nil
:section-numbers nil
:table-of-contents nil
:base-extension "org"
:publishing-function (org-html-publish-to-html org-org-publish-to-org)
:style-include-default nil
:html-head "<link rel=\"stylesheet\" href=\"/org.css\" type=\"text/css\" />"
:author-info nil
:creator-info nil)
("doc-extra"
:base-directory "~/git/doc.norang.ca/"
:publishing-directory "/ssh:[email protected]:~/doc.norang.ca/htdocs"
:base-extension "css\\|pdf\\|png\\|jpg\\|gif"
:publishing-function org-publish-attachment
:recursive nil
:author nil)
("doc"
:components ("doc-org" "doc-extra"))
("doc-private-org"
:base-directory "~/git/doc.norang.ca/private"
:publishing-directory "/ssh:[email protected]:~/doc.norang.ca/htdocs/private"
:recursive nil
:section-numbers nil
:table-of-contents nil
:base-extension "org"
:publishing-function (org-html-publish-to-html org-org-publish-to-org)
:style-include-default nil
:html-head "<link rel=\"stylesheet\" href=\"/org.css\" type=\"text/css\" />"
:auto-sitemap t
:sitemap-filename "index.html"
:sitemap-title "Norang Private Documents"
:sitemap-style "tree"
:author-info nil
:creator-info nil)
("doc-private-extra"
:base-directory "~/git/doc.norang.ca/private"
:publishing-directory "/ssh:[email protected]:~/doc.norang.ca/htdocs/private"
:base-extension "css\\|pdf\\|png\\|jpg\\|gif"
:publishing-function org-publish-attachment
:recursive nil
:author nil)
("doc-private"
:components ("doc-private-org" "doc-private-extra"))
;
; Miscellaneous pages for other websites
; org are the org-files that generate the content
("org-org"
:base-directory "~/git/org/"
:publishing-directory "/ssh:[email protected]:~/org"
:recursive t
:section-numbers nil
:table-of-contents nil
:base-extension "org"
:publishing-function org-html-publish-to-html
:style-include-default nil
:html-head "<link rel=\"stylesheet\" href=\"/org.css\" type=\"text/css\" />"
:author-info nil
:creator-info nil)
;
; http://doc.norang.ca/ (norang website)
; org-mode-doc-org this document
; org-mode-doc-extra are images and css files that need to be included
; org-mode-doc is the top-level project that gets published
; This uses the same target directory as the 'doc' project
("org-mode-doc-org"
:base-directory "~/git/org-mode-doc/"
:publishing-directory "/ssh:[email protected]:~/doc.norang.ca/htdocs"
:recursive t
:section-numbers nil
:table-of-contents nil
:base-extension "org"
:publishing-function (org-html-publish-to-html)
:plain-source t
:htmlized-source t
:style-include-default nil
:html-head "<link rel=\"stylesheet\" href=\"/org.css\" type=\"text/css\" />"
:author-info nil
:creator-info nil)
("org-mode-doc-extra"
:base-directory "~/git/org-mode-doc/"
:publishing-directory "/ssh:[email protected]:~/doc.norang.ca/htdocs"
:base-extension "css\\|pdf\\|png\\|jpg\\|gif\\|org"
:publishing-function org-publish-attachment
:recursive t
:author nil)
("org-mode-doc"
:components ("org-mode-doc-org" "org-mode-doc-extra"))
;
; http://doc.norang.ca/ (norang website)
; org-mode-doc-org this document
; org-mode-doc-extra are images and css files that need to be included
; org-mode-doc is the top-level project that gets published
; This uses the same target directory as the 'doc' project
("tmp-org"
:base-directory "/tmp/publish/"
:publishing-directory "/ssh:[email protected]:~/www.norang.ca/htdocs/tmp"
:recursive t
:section-numbers nil
:table-of-contents nil
:base-extension "org"
:publishing-function (org-html-publish-to-html org-org-publish-to-org)
:html-head "<link rel=\"stylesheet\" href=\"http://doc.norang.ca/org.css\" type=\"text/css\" />"
:plain-source t
:htmlized-source t
:style-include-default nil
:auto-sitemap t
:sitemap-filename "index.html"
:sitemap-title "Test Publishing Area"
:sitemap-style "tree"
:author-info t
:creator-info t)
("tmp-extra"
:base-directory "/tmp/publish/"
:publishing-directory "/ssh:[email protected]:~/www.norang.ca/htdocs/tmp"
:base-extension "css\\|pdf\\|png\\|jpg\\|gif"
:publishing-function org-publish-attachment
:recursive t
:author nil)
("tmp"
:components ("tmp-org" "tmp-extra")))))
; I'm lazy and don't want to remember the name of the project to publish when I modify
; a file that is part of a project. So this function saves the file, and publishes
; the project that includes this file
;
; It's bound to C-S-F12 so I just edit and hit C-S-F12 when I'm done and move on to the next thing
(defun bh/save-then-publish (&optional force)
(interactive "P")
(save-buffer)
(org-save-all-org-buffers)
(let ((org-html-head-extra)
(org-html-validation-link "<a href=\"http://validator.w3.org/check?uri=referer\">Validate XHTML 1.0</a>"))
(org-publish-current-project force)))
(global-set-key (kbd "C-s-<f12>") 'bh/save-then-publish)
主項目是
norang
，
doc
,
doc-private
,
org-mode-doc
以及
tmp
。這些項目自動釋出到web 伺服器相應目錄。當釋出時候将會導出所有修改的頁面，生成圖檔以及拷貝相應的檔案到web伺服器中，是以友善立馬檢視。
網站 http://doc.norang.ca/ 包含所有客戶私密文檔（是以要配置通路權限）通路權 限通過Apache通路權限控制來實作。我不會從公共頁面建立這些文檔連結(用以通路它們)。http://doc.norang.ca/someclient/ 會顯示在路徑
~/git/doc.norang.ca/someclient/
所有的org檔案索引如果該網站被設定可視的話。我會使用這些網站上大部分資訊，當然如果 我的客戶對這些資訊感興趣，我也會給他們開權限檢視。
這樣很棒，我知道我的備忘在網站上，并且我可以通路他們。我也友善跟其他人分享 備忘，隻要給他們相應的連結(并開通通路權限)即可。
我所要記的就是修改合适的org檔案，然後通過C-S-F12釋出–不是特别難:)
我有個臨時的釋出網站用來驗證釋出項目。這個就是
tmp
網站，它将
/tmp/publish
檔案拷貝過來，導出這些檔案到釋出路徑。這友善線上測試一些新功能。
1.8 其他導出設定
這些是我收集的關于導出和釋出相關的設定腳本。
1.8.1 加強源碼 Latex lists
當要導出為latex格式，我使用下列設定加強源碼清單:
(setq org-latex-listings t)
1.8.2 不帶XML頭導出HTML
我使用下列設定移除HTML方式導出的文檔中的xml頭。如果不移除這些XML頭，當通過open Office打開HTML将其轉換成ODT。
(setq org-html-xml-declaration (quote (("html" . "")
("was-html" . "<?xml version=\"1.0\" encoding=\"%s\"?>")
("php" . "<?php echo \"<?xml version=\\\"1.0\\\" encoding=\\\"%s\\\" ?>\"; ?>"))))
1.8.3 導出時允許綁定參數導出
下面設定允許設定 #+BIND: 這樣在導出時候可以綁定一些參數，導出時候就不需要再次确認。在極少情況下我會覆寫一些org-mode一些導出參數。這樣在導出時候就不會彈出提示。
(setq org-export-allow-BIND t)