Org-mode, 用文本文件管理日常(十一)

最新推荐文章于 2024-08-23 10:01:02 发布

xxpyb

最新推荐文章于 2024-08-23 10:01:02 发布

阅读量933

点赞数

分类专栏： emacs org 文章标签： emacs lisp gtd plugin html

原文链接：http://doc.norang.ca/org-mode.html

版权

org 同时被 2 个专栏收录

15 篇文章 1 订阅

订阅专栏

emacs

13 篇文章 0 订阅

订阅专栏

本文详细介绍了使用Org-mode进行日常管理的发布导出功能，包括新的导出设置、org-babel的配置、ditta、graphviz和PlantUML的使用，以及如何发布单个文件和项目。Org-mode支持多种格式的导出，如HTML、LaTeX等，通过设置可以方便地生成和管理在线文档。

摘要由CSDN通过智能技术生成

本文翻译自 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=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: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一些导出参数。这样在导出时候就不会弹出提示。