Next: Images and link previews, Previous: Embedded LaTeX, Up: Markup for Rich Contents   [Contents][Index]

12.6 Literal Examples ¶

你可以插入无需标记处理的字面示例，这类示例以等宽字体排版，非常适合展示源码及类似内容。

#+BEGIN_EXAMPLE
  Some example from a text file.
#+END_EXAMPLE

但存在一个限制：以 ‘*’ 、 ‘,*’ 、 ‘#+’ 或 ‘,#+’ 开头的行，必须在行首插入一个逗号，因为这些字符可能被识别为大纲节点或其他特殊语法。Org 在读取块内容时会自动移除这些额外的逗号。

#+BEGIN_EXAMPLE
,* I am no real headline
#+END_EXAMPLE

对于小型示例，简化写法是在行首以冒号加空格开头，冒号前也可包含额外空白：

Here is an example
   : Some example from a text file.

若示例为编程语言源码或其他可在 Emacs 中通过 Font Lock 高亮的文本，可让示例显示为 Emacs 高亮后的样式¹¹⁷。这通过代码块实现，同时需要指定用于高亮的主模式名称¹¹⁸，快速插入代码块的方法见 Structure Templates。

#+BEGIN_SRC emacs-lisp
  (defun org-xor (a b)
    "Exclusive or."
    (if a (not b) b))
#+END_SRC

在 ‘example’ 和 ‘src’ 代码片段中，可在 ‘#+BEGIN’ 行添加 ‘-n’ 参数¹¹⁹，为示例行添加行号。=-n= 可接受可选数字参数，指定块的起始行号。使用 ‘+n’ 参数时，当前块会接续上一个编号片段的行号继续计数。 ‘+n’ 也可接受数字参数，该值会与上一个块的最后一行相加，作为当前块的起始行号。

#+BEGIN_SRC emacs-lisp -n 20
  ;; This exports with line number 20.
  (message "This is line 21")
#+END_SRC

#+BEGIN_SRC emacs-lisp +n 10
  ;; This is listed as line 31.
  (message "This is line 32")
#+END_SRC

在字面示例中，Org 会将 ‘(ref:name)’ 这类字符串识别为标签，并作为特殊超链接的目标，如 ‘[[(name)]]’—即引用名放在单括号内。在 HTML 中，鼠标悬停在这类链接上时，会远程高亮对应的代码行¹²⁰。

你还可以添加 ‘-r’ 参数，从源码中 移除(removes) 标签¹²¹。使用 ‘-n’ 参数时，指向这些引用的链接会使用代码清单中的行号标记；否则链接使用不带括号的标签。示例如下：

#+BEGIN_SRC emacs-lisp -n -r
  (save-excursion                 (ref:sc)
     (goto-char (point-min))      (ref:jump)
#+END_SRC
In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]]
jumps to point-min.

源码与示例可以进行 缩进(indented) ，以便与周围文本（尤其是普通列表结构，见 Plain Lists）对齐。默认情况下，Org 仅保留行之间的相对缩进，例如导出块内容时。但若有必要，可使用 ‘-i’ 参数保留全局缩进。见 Editing Source Code。

若标签格式语法与语言语法冲突，可使用 ‘-l’ 参数修改格式，例如：

#+BEGIN_SRC pascal -n -r -l "((%s))"

另见变量 org-coderef-label-format 。

HTML 导出还支持将示例发布为文本区域，见 Text areas in HTML export。

由于 ‘#+BEGIN’ … ‘#+END’ 结构需要频繁添加，Org 提供了快捷方式（见 Structure Templates）。

C-c ' (org-edit-special) ¶

在对应原生模式下编辑光标处的源码示例。该操作会切换到临时缓冲区编辑源码，完成后按 C-c ' 退出，编辑后的内容会替换 Org 缓冲区中的旧内容。等宽区域（每行以冒号加空格开头）会使用 Artist 模式¹²²编辑，方便绘制 ASCII 图形。在空行使用该命令会新建一个等宽区域。

在通过 C-c ' 创建的临时缓冲区中编辑源码示例时，调用 org-store-link （见 Handling Links）会提示输入标签。确保其在当前缓冲区唯一，并以 ‘(ref:label)’ 格式插入当前行尾。随后该标签会以 ‘(label)’ 形式存储为链接，可通过 C-c C-l 调用。