all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
blob 238586e9f428fe87658687029dadc1152e2a8ab3 10134 bytes (raw)
name: zh_CN/quickstart.org 	 # note: path name is non-authoritative(*)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
#+TITLE: 快速开始 | Org 主模式
#+setupfile: setup.org
#+include: "resources/preamble.html" export html

* 开始使用 Org@@comment:Get Started@@
  :PROPERTIES:
  :CUSTOM_ID: getting-started
  :END:

简单来说,Org 与任何其它的标记语言一样:你可以在任何文本编辑器里使用 [[file:../worg/dev/org-syntax.html][Org 语法]] 编辑文档。

然而,为了体验 Org 全部的潜力,你需要一个能够把 Org 语法转换为一个可互动文档的编辑器。

#+begin_center
#+attr_html: :class btn
*[[file:../org.html#Installation][安装 Org]]*
#+end_center

* 文档引言@@comment:Preamble@@
  :PROPERTIES:
  :CUSTOM_ID: preamble
  :END:

在文件的最开始(第一个章节标题之前),你常常需要设置标题、作者以及其它[[file:../manual/Export-Settings.html][导出选项]]。

#+BEGIN_SRC org
,#+title: Org 的荣光
,#+author: Org 用户
#+END_SRC

* 章节标题@@comment:Heading@@
  :PROPERTIES:
  :CUSTOM_ID: headings
  :END:

由星号 ~*~ 开始的行被称作[[file:../worg/dev/org-syntax.html#Headlines_and_Sections][章节标题(heading)]]。

一个星号 ~*~ 代表一级章节标题,两个星号 ~**~ 代表二级章节标题,等等。

#+BEGIN_SRC org
  ,* 欢迎来到 Org
  ,** 子章节标题
  每个额外的 ~*~ 为章节的深度增加一级。
#+END_SRC

简单来说,章节标题代表了一个章节的开始。然而,任何章节也可以成为一个[[file:../manual/TODO-Items.html][待办事项]]。

待办事项是 Org 用来跟踪、整理各类的任务的基本模块。

若要把一个现有的章节标题转换为一个待办事项,仅需在其开头加上一个待办关键词,例如 ~TODO~ 或者 ~HOLD~​。

#+BEGIN_SRC org
  ,* TODO 向世界介绍 Org
  ,** TODO 创建一个快速开始指南
#+END_SRC

* 标记@@comment:markup@@
  :PROPERTIES:
  :CUSTOM_ID: markup
  :END:

# 代码 = code; 逐字 = verbatim
若要在 Org 里标记文字,仅需要在其两侧使用标记字符。​*加粗*​、​/斜体/​、​_下划线_​都很简单;你甚至能够轻松地使用​+删除线+​。你可以任意组合这些基本的标记,但需要记住一点,若使用了​~代码~​或​=逐字=​这两个标记之一,它们需要在这个组合的​*_~最里侧~_*​,因为它们包含的内容是​=按字面=​解析的。

#+begin_example
若要在 Org 里标记文字,仅需要在其两侧使用标记字符。​*加粗*​、​/斜体/​、​_下划线_​都很简单;你甚至能够轻松地使用​+删除线+​。你可以任意组合这些基本的标记,但需要记住一点,若使用了​~代码~​或​=逐字=​这两个标记之一,它们需要在这个组合的​*_~最里侧~_*​,因为它们包含的内容是​=按字面=​解析的。
#+end_example

可在[[file:../worg/dev/org-syntax.html#Emphasis_Markers][标记符号(英语)]]里查看更多信息。

** 中文用户
中文用户_​:由于 Org 的限制,标记字符的内侧必须不是空格,而外侧必须是空格(包含换行等)。因此,中文用户需要在使用标记时,可以在有需要时使用零宽空格(16进制代码​~#x200b~​,名称为​~ZERO WIDTH SPACE~​)。使用方法:

(原生 Emacs)快捷键:
#+begin_example
C-x 8 RET 200b RET
#+end_example

使用 Emacs Lisp:
#+begin_src emacs-lisp
(insert-char #x200b)
#+end_src

* 列表@@comment:Lists@@
  :PROPERTIES:
  :CUSTOM_ID: lists
  :END:

# 无序列表 = unordered list; 有序列表 = ordered list
无序列表由​~+~​、​~-~​、​~*~​开头​[fn::~*~​不能被用作一行的最开头,因为这样它会被解析成一个章节标题。]。有序列表由​~1.~​、​~1)~​、​~A.~​、​~A)~​开头。有序与无序符号可以以任意顺序嵌套。

#+BEGIN_SRC org
  采购单:
  1. 牛奶
  2. 鸡蛋
     - 有机
  3. 调料
     + 糖
     + 盐
#+END_SRC

# 勾选项 = checkbox
列表可包含勾选项​~[ ]~​、​~[-]~​、​~[X]~​。
#+BEGIN_SRC org
  - [ ] 未开始
  - [-] 进行中
  - [X] 已完成
#+END_SRC

# 标签 = tag
列表也可同时包含标签。
#+BEGIN_SRC org
  - [ ] 水果 :: 买苹果
  - [X] 蔬菜 :: 买胡萝卜
#+END_SRC

* 链接
  :PROPERTIES:
  :CUSTOM_ID: links
  :END:

创建链接时把目标放在两对​*半角*​方括号中,例如:​~[[目标]]~​。你也可以在链接里、目标之后添加描述:​~[[目标][描述]]~​。

这个顺序相当好记,因为这跟 HTML 的 =<a>= 标记 ~<a href="目标">描述</a>~ 一样,并且你不可能混淆不同种类的括号,因为 Org 语法里只用中括号。

Org 支持一系列不同的链接目标类型,并且你还可以[[file:../manual/Adding-Hyperlink-Types.html][添加你自己的目标类型]]。链接目标类型由其前缀​~类型:~​表示,例如:​~[[类型:目标]]~​。若没有提供类型,Org 会在当前文件里搜索一个符合​~目标~​的章节标题。

举个例子:
#+BEGIN_EXAMPLE
[[https://orgmode.org][一个网页]]
[[file:~/Pictures/dank-meme.png]]
[[之前的章节标题][此文档里一个之前的章节标题]]
#+END_EXAMPLE

** 更多信息
更多关于链接的信息参见手册(英语):[[file:../manual/Internal-Links.html][内部链接]]、[[file:../manual/External-Links.html][外部链接]]。

* 图像
  :PROPERTIES:
  :CUSTOM_ID: images
  :END:

Org 会在导出时自动识别且显示图片链接。你只需要链接一个图片,且不提供描述既可。\\
~[[https://orgmode.org/resources/img/quickstart.svg]]~

#+attr_html: :height 120px
[[file:../resources/img/quickstart.svg]]

在你电脑里的图片也可以按 =C-c C-x C-v= 在 Emacs 缓存区里显示。

* 区块
  :PROPERTIES:
  :CUSTOM_ID: blocks
  :END:

Org 主模式里可以包含区块 =#+BEGIN= …… =#+END=​,不同的区块对应不同的用途。基本的区块包括:引用(quote),举例(example),以及源码(src)。

若你只需要等宽文字,你可以使用举例区块。
#+BEGIN_SRC org
,#+begin_example
monospace 等宽
,#+end_example
#+END_SRC

然而,你不能在举例区块里使用 [[file:../worg/org-contrib/babel/][Org Babel]] ----- 你需要使用源码区块。源码区块提供了语法高亮、代码运行、文学编程等等。
#+BEGIN_SRC org
,#+begin_src emacs-lisp
(message "Hello world")
,#+end_src
#+END_SRC

** 更多信息
一个”你好世界“的例子根本不足以向你展示 Org 与源代码的[[file:../manual/Working-with-Source-Code.html][所有功能]]。

* 表格
  :PROPERTIES:
  :CUSTOM_ID: tables
  :END:

Org 主模式内置了一个表格编辑器,并且支持各种与元素引用以及公式的功能。

最简单的表格仅仅是由 ~|~ 分隔开的文本。
#+BEGIN_SRC org
| 我 | 是 | 一个 | 表格 |
| 我 | 有 | 两行 | !   |
#+END_SRC

这是在一篇论文([[doi:10.18637/jss.v046.i03][Schulte /et al./ 2012]])里的一个表格,对比了现有的文学编程与可重复研究工具。

#+BEGIN_SRC org
| Tool         | Literate programming? | Reproducible Research? | Languages |
|--------------+-----------------------+------------------------+-----------|
| Javadoc      | partial               | no                     | Java      |
| Haskell .lhs | partial               | no                     | Haskell   |
| noweb        | yes                   | no                     | any       |
| Sweave       | partial               | yes                    | R         |
| Org-mode     | yes                   | yes                    | any       |
#+END_SRC

担心无法在文本表格中对齐?你只需按一个键 ----- =tab=​。

* 注释
  :PROPERTIES:
  :CUSTOM_ID: comments
  :END:

在 Org 里有很多种方法添加注释:

- 行注释:用​~#~​开头。
- 行内注释:把注释包起来(​~@@comment:就像这样@@~​)。
- 区块注释:用​~#+BEGIN_COMMENT~​和​~#+END_COMMENT~​把注释包起来。
- 章节注释:在章节标题前加上 ~COMMENT~ 可以把这整个章节变成注释[fn::还有一些对章节的更精细的操作,包括使用特殊章节标签​~:ARCHIVE:~​以及​~:noexport:~​。]。

#+BEGIN_SRC org
# 一个行注释

这是一个​@@comment:行内@@​注释。

行内注释可同时被用作行末注释。​@@comment:~#~没有用@@
这是因为​~#~​只在作为一行第一个非空格字符时才是行注释。

,#+begin_comment
这是一个区块注释。
它可以跨越多行,或者其它标记与区块定义。
,#+begin_src emacs-lisp
(+ 1 2)
,#+end_src
,#+end_comment

,* 一个顶层章节标题
,** COMMENT 这个章节与其子章节是注释
,*** 这个章节继承了关键词​=COMMENT=
这段文字是注释
,** 这个章节不是注释
这段文字会被导出,且代码区块会被运行。
#+END_SRC

** 中文用户
_中文用户_​:​=@@comment:行内注释@@=​两侧需要使用零宽空格,详见[[*标记][此章节]]。

* 宏
  :PROPERTIES:
  :CUSTOM_ID: macros
  :END:

  Org 的语法拥有更多高级功能,[[file:../manual/Macro-Replacement.html][这里]]有一个简单的例子。

#+BEGIN_SRC org
,#+macro: attn _*/$1/*_
{{{attn(注意!这个文本有所有标记!)}}}

,#+html_head: <style>.red{color:red;}</style>
,#+latex_header: \usepackage{xcolor}
,#+macro: red @@html:<span class="red">$1</span>@@@@latex:\textcolor{red}{$1}@@
普通文本。{{{red(红色文本。)}}}更多普通文本。
#+END_SRC

* 下一步
  :PROPERTIES:
  :CUSTOM_ID: next-steps
  :END:

在寻找某一个话题?试着读读[[file:../manual/][手册(英语)]]([[file:../org.pdf][PDF]])吧。

在寻找这个快速开始与手册之间的内容?试试[[file:../guide/][指导(英语)]]([[file:../orgguide.pdf][PDF]])吧。

debug log:

solving ddf1b3e ...
found ddf1b3e in https://yhetil.org/emacs/sdvjzyjzkzo.fsf@fw.net.yu/

applying [1/1] https://yhetil.org/emacs/sdvjzyjzkzo.fsf@fw.net.yu/
diff --git a/zh_CN/quickstart.org b/zh_CN/quickstart.org\r
new file mode 100644\r
index 0000000..ddf1b3e\r

1:7: trailing whitespace.
#+TITLE: 快速开始 | Org 主模式\r
1:8: trailing whitespace.
#+setupfile: setup.org\r
1:9: trailing whitespace.
#+include: "resources/preamble.html" export html\r
1:10: trailing whitespace.
\r
1:11: trailing whitespace.
* 开始使用 Org@@comment:Get Started@@\r
Checking patch zh_CN/quickstart.org...
Applied patch zh_CN/quickstart.org cleanly.
warning: squelched 260 whitespace errors
warning: 265 lines add whitespace errors.

index at:
100644 238586e9f428fe87658687029dadc1152e2a8ab3	zh_CN/quickstart.org

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.