本文翻译自 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列表

  负值将不会在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=expandedge [dir=both]plcnet [shape=box, label="PLC Network"]subgraph cluster_wrapline {label="Wrapline Control System"color=purplesubgraph {rank=sameexecsharedmem [style=filled, fillcolor=lightgrey, shape=box]}edge[style=dotted, dir=none]exec -> opserverexec -> dbplc -> execedge [style=line, dir=both]exec -> sharedmemsharedmem -> dbplc -> sharedmemsharedmem -> opserver}plcnet -> plc [constraint=false]millwide [shape=box, label="Millwide System"]db -> millwidesubgraph cluster_opclients {color=bluelabel="Operator Clients"rankdir=LRlabelloc=bnode[label=client]opserver -> client1opserver -> client2opserver -> 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:www-data@www:~/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:www-data@www:~/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:www-data@www:~/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:www-data@www:~/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:www-data@www:~/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:www-data@www:~/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:www-data@www:~/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:www-data@www:~/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:www-data@www:~/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:www-data@www:~/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:www-data@www:~/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)