写作即编程

Transcript

1. 写作即编程 黄增光（@chloerei） <chloerei@gmail.com>
2. 关于我 Web 开发者
3. https://ruby-china.org/rei
4. https://selfstore.io
5. 写作与我相关吗？
6. 沟通 How To Ask Questions The Smart Way — Eric S. Raymond 如果你人为地将问题搞得难以阅读，它 多半会被忽略，人们更愿读易懂的问 题。
7. 分享 — Joel Spolsky 杰出的程序员跟勉强过得去的程序员之 间的差别，不在于它们掌握了多少种编 程语言……真正的关键是，他们能不能 把他们的想法表达清楚。
8. 产品文档 发布（HTML/PDF） 多人协作 版本管理
9. MARKDOWN
10. 支持 MARKDOWN 的网站 Stack Overflow GitHub Ruby China …​
11. example.md # A F i r s t L e v e l H e a d e r # # A S e c o n d L e v e l H e a d e r N o w i s t h e t i m e f o r a l l g o o d m e n t o c o m e t o t h e a i d o f t h e i r c o u n t r y . T h i s i s j u s t a r e g u l a r p a r a g r a p h . T h e q u i c k b r o w n f o x j u m p e d o v e r t h e l a z y d o g ' s b a c k . # # # H e a d e r 3 > T h i s i s a b l o c k q u o t e . > > T h i s i s t h e s e c o n d p a r a g r a p h i n t h e b l o c k q u o t e . >
12. $ g e m i n s t a l l r e d c a r p e t $ r e d c a r p e t e x a m p l e . m d > e x a m p l e . h t m l
13. example.html < h 1 > F i r s t L e v e l H e a d e r < / h 1 > < h 2 > A S e c o n d L e v e l H e a d e r < / h 2 > < p > N o w i s t h e t i m e f o r a l l g o o d m e n t o c o m e t o t h e a i d o f t h e i r c o u n t r y . T h i s i s j u s t a r e g u l a r p a r a g r a p h . < / p > < p > T h e q u i c k b r o w n f o x j u m p e d o v e r t h e l a z y d o g & # 3 9 ; s b a c k . < / p > < h 3 > H e a d e r 3 < / h 3 > < b l o c k q u o t e > < p > T h i s i s a b l o c k q u o t e . < / p > < p > T h i s i s t h e s e c o n d p a r a g r a p h i n t h e b l o c k q u o t e . < / p >
14. r e q u i r e ' r e d c a r p e t ' # I n i t i a l i z e s a M a r k d o w n p a r s e r m a r k d o w n = R e d c a r p e t : : M a r k d o w n . n e w ( r e n d e r e r , e x t e n s i o n s = { } ) m a r k d o w n . r e n d e r ( " T h i s i s * b o n g o s * , i n d e e d . " ) # = > " < p > T h i s i s < e m > b o n g o s < / e m > , i n d e e d . < / p > "
15. ATOM
16. MARKDOWN 语法
17. 标题 # 一级标题 # # 二级标题 # # # 三级标题 < h 1 > 一级标题< / h 1 > < h 2 > 二级标题< / h 2 > < h 3 > 三级标题< / h 3 >
18. 精通 H5 # # # # # 应用 # # # # # 游戏 # # # # # 页面 < h 5 > 应用< / h 5 > < h 5 > 游戏< / h 5 > < h 5 > 页面< / h 5 >
19. Tip 标题不等于大号加粗
20. Tip 空格空行都是有意义的
21. 段落 在我的后园，可以看见墙外有两株树，一株是枣树，还有一株也是枣树。 这上面的夜的天空，奇怪而高，我生平没有见过这样奇怪而高的天空。 < p > 在我的后园，可以看见墙外有两株树，一株是枣树，还有一株也是枣树。< / p > < p > 这上面的夜的天空，奇怪而高，我生平没有见过这样奇怪而高的天空。< / p >
22. Tip 换行（\ n ）不是换行（< b r > ）。
23. 这是第一行 这是第二行 < p > 这是第一行 这是第二行< / p > 这是第一行 这是第二行
24. 换行方法一：行末加两个空格。 这是第一行 这是第二行 < p > 这是第一行< b r > 这是第二行< / p >
25. 换行方法二：修改渲染器。 $ r e d c a r p e t ­ ­ r e n d e r ­ h a r d _ w r a p b r e a k l i n e . m d < p > 这是第一行< b r > 这是第二行< / p >
26. 引用 > 在我的后园，可以看见墙外有两株树，一株是枣树，还有一株也是枣树。 > 这上面的夜的天空，奇怪而高，我生平没有见过这样奇怪而高的天空。 < b l o c k q u o t e > < p > 在我的后园，可以看见墙外有两株树，一株是枣树，还有一株也是枣树。< / p > < p > 这上面的夜的天空，奇怪而高，我生平没有见过这样奇怪而高的天空。< / p > < / b l o c k q u o t e >
27. 代码块 d e f f o o p u t s " h e l l o w o r l d " e n d < p r e > < c o d e > d e f f o o p u t s " h e l l o w o r l d " e n d < / c o d e > < / p r e >
28. GITHUB FLAVORED MARKDOWN (GFM) ` ` ` r u b y d e f f o o p u t s " h e l l o w o r l d " e n d ` ` `
29. 有序列表 1 . 有序列表 2 . 有序列表 3 . 有序列表 < o l > < l i > 有序列表< / l i > < l i > 有序列表< / l i > < l i > 有序列表< / l i > < / o l >
30. 无序列表 * 无序列表 * 无序列表 * 无序列表 < u l > < l i > 无序列表< / l i > < l i > 无序列表< / l i > < l i > 无序列表< / l i > < / u l >
31. 文字样式 * 斜体* * * 加粗* * ` 代码` < e m > 斜体< / e m > < s t r o n g > 加粗< / s t r o n g > < c o d e > 代码< / c o d e >
32. 链接/图片 [ 链接] ( h t t p : / / e x a m p l e . o r g / ) ! [ 图片] ( h t t p : / / e x a m p l e . o r g / i m a g e . p n g ) < a h r e f = " h t t p : / / e x a m p l e . o r g / " > 链接< / a > < i m g s r c = " h t t p : / / e x a m p l e . o r g / i m a g e . p n g " a l t = " 图片" >
33. MARKDOWN 的应用场景
34. JEKYLL
35. MIDDLEMAN
37. GITBOOK
38. MARKDOWN 的局限
39. 功能少 缺少表格、脚注、目录、拆分文件……
40. 太多方言 GitHub Flavor、Stack Overflow Flavor……
41. 不一致 # H e l l o t h e r e T h i s i s a p a r a g r a p h . ­ o n e ­ t w o ­ t h r e e ­ f o u r 1 . p i r a t e 2 . n i n j a 3 . z o m b i e http://johnmacfarlane.net/babelmark2/
42. http://commonmark.org/
43. 又一个方言
44. 我们需要更好的标记语言。
45. 简单和强大冲突吗？
46. ASCIIDOC
47. AsciiDoc 发布于 2002-11-25。 Markdown 发布于 2004-3-19。
48. AsciiDoc → DocBook
49. example.adoc = H e l l o , A s c i i D o c ! D o c W r i t e r < d o c @ e x a m p l e . c o m > A n i n t r o d u c t i o n t o h t t p : / / a s c i i d o c . o r g [ A s c i i D o c ] . = = F i r s t S e c t i o n * i t e m 1 * i t e m 2 [ s o u r c e , r u b y ] ­ ­ ­ ­ p u t s " H e l l o , W o r l d ! " ­ ­ ­ ­
50. ASCIIDOCTOR $ g e m i n s t a l l a s c i i d o c t o r $ a s c i i d o c t o r e x a m p l e . a d o c
52. r e q u i r e ' a s c i i d o c t o r ' c o n t e n t = ' _ Z e n _ i n t h e a r t o f w r i t i n g h t t p : / / a s c i i d o c t o r . o r g [ A s c i i D o c ] . ' A s c i i d o c t o r . c o n v e r t c o n t e n t # = > " < d i v c l a s s = \ " p a r a g r a p h \ " > \ n < p > < e m > Z e n < / e m > i n t h e a r t o f w r i t i n g < a h r e
53. ATOM $ a p m i n s t a l l l a n g u a g e ­ a s c i i d o c a s c i i d o c ­ p r e v i e w
55. jekyll-asciidoc middleman-asciidoc GitBook v2+
56. ASCIIDOC 语法
57. 文档标题和属性 = 文档标题 作者 < a u t h o r @ e x a m p l e . o r g > : a p p v e r s i o n : 1 . 0 . 0
58. 章节标题 = 文档标题 = = 一级标题 = = = 二级标题 = = = = 三级标题
59. = 文档标题 : t o c : = = 第一章 = = = 第一节 = = = 第二节 = = 第二章 = = 第三章
61. 段落 在我的后园，可以看见墙外有两株树，一株是枣树，还有一株也是枣树。 这上面的夜的天空，奇怪而高，我生平没有见过这样奇怪而高的天空。
62. 换行方法一：行末加 ` +` 第一行 + 第二行
63. 换行方法二：段落属性 [ % h a r d b r e a k s ] 第一行 第二行
64. 换行方法三：全局属性 = 文档标题 : h a r d b r e a k s : 第一行 第二行
65. 引用 _ _ _ _ 在我的后园，可以看见墙外有两株树，一株是枣树，还有一株也是枣树。 _ _ _ _ [ q u o t e , 鲁迅] _ _ _ _ 在我的后园，可以看见墙外有两株树，一株是枣树，还有一株也是枣树。 _ _ _ _ [ q u o t e , 鲁迅, 《秋夜》] _ _ _ _ 在我的后园，可以看见墙外有两株树，一株是枣树，还有一株也是枣树。 _ _ _ _
67. 图片 i m a g e : : p a t h / t o / i m a g e . p n g [ ] i m a g e : : h t t p s : / / r u b y ­ c h i n a . o r g / l o g o . p n g [ ]
68. . R u b y C h i n a L o g o i m a g e : : i m a g e s / r u b y ­ c h i n a . p n g [ w i d t h = 3 0 0 ]
69. 音频/视频 a u d i o : : p a t h / t o / a u d i o . o g g [ ] v i d e o : : p a t h / t o / v i d e o . o g g [ ]
70. 表格 . T a b l e T i t l e | = = = | N a m e o f C o l u m n 1 | N a m e o f C o l u m n 2 | N a m e o f C o l u m n 3 | C e l l i n c o l u m n 1 , r o w 1 | C e l l i n c o l u m n 2 , r o w 1 | C e l l i n c o l u m n 3 , r o w 1 | C e l l i n c o l u m n 1 , r o w 2 | C e l l i n c o l u m n 2 , r o w 2 | C e l l i n c o l u m n 3 , r o w 2 | = = =
72. [ f o r m a t = " c s v " , o p t i o n s = " h e a d e r " ] | = = = A r t i s t , T r a c k , G e n r e B a a u e r , H a r l e m S h a k e , H i p H o p T h e L u m i n e e r s , H o H e y , F o l k R o c k | = = =
73. [ f o r m a t = " c s v " , o p t i o n s = " h e a d e r " ] | = = = i n c l u d e : : c u s t o m e r s . c s v [ ] | = = =
74. 代码块 [ s o u r c e , r u b y ] ­ ­ ­ ­ r e q u i r e ' s i n a t r a ' g e t ' / h i ' d o " H e l l o W o r l d ! " e n d ­ ­ ­ ­
75. 标注 : s o u r c e ­ h i g h l i g h t e r : c o d e r a y : i c o n s : f o n t . h e l l o _ w o r l d . r b [ s o u r c e , r u b y ] ­ ­ ­ ­ r e q u i r e ' s i n a t r a ' # < 1 > g e t ' / h i ' d o # < 2 > " H e l l o W o r l d ! " # < 3 > e n d ­ ­ ­ ­ < 1 > L i b r a r y i m p o r t < 2 > U R L m a p p i n g < 3 > C o n t e n t f o r r e s p o n s e
77. 脚注 * 原汁海螺 2 8 元 * 原汁扇贝 1 0 元 * 海捕大虾 3 8 元 f o o t n o t e : [ 以上海鲜按个计价]
78. 警告 : f o n t s : i c o n T I P : P r o t i p . . . I M P O R T A N T : D o n ' t f o r g e t . . . W A R N I N G : W a t c h o u t f o r . . . C A U T I O N : E n s u r e t h a t . . .
80. INCLUDE index.adoc = D o c u m e n t T i t l e i n c l u d e : : s e c t i o n s / c h a p t e r _ 1 . a d o c [ ] i n c l u d e : : s e c t i o n s / c h a p t e r _ 2 . a d o c [ ] i n c l u d e : : s e c t i o n s / c h a p t e r _ 3 . a d o c [ ] . | ­ ­ i n d e x . a d o c ` ­ ­ s e c t i o n s | ­ ­ c h a p t e r _ 1 . a d o c | ­ ­ c h a p t e r _ 2 . a d o c ` ­ ­ c h a p t e r _ 3 . a d o c
81. BLOCK . T i t l e [ B l o c k n a m e , A t t r i b u t e s ] ­ ­ C o n t e n t ­ ­
82. 自定义 BLOCK [ s h o u t ] ­ ­ T h e t i m e i s n o w . G e t a m o v e o n . ­ ­
83. r e q u i r e ' a s c i i d o c t o r ' r e q u i r e ' a s c i i d o c t o r / e x t e n s i o n s ' c l a s s S h o u t B l o c k < A s c i i d o c t o r : : E x t e n s i o n s : : B l o c k P r o c e s s o r P e r i o d R x = / \ . ( ? = | $ ) / u s e _ d s l n a m e d : s h o u t o n _ c o n t e x t : p a r a g r a p h n a m e _ p o s i t i o n a l _ a t t r i b u t e s ' v o l ' p a r s e _ c o n t e n t _ a s : s i m p l e d e f p r o c e s s p a r e n t , r e a d e r , a t t r s v o l u m e = ( ( a t t r s . d e l e t e ' v o l ' ) | | 1 ) . t o _ i c r e a t e _ p a r a g r a p h p a r e n t , ( r e a d e r . l i n e s . m a p { | l | l . u p c a s e . g s u b P e r i o d R x e n d
84. A s c i i d o c t o r : : E x t e n s i o n s . r e g i s t e r d o b l o c k S h o u t B l o c k e n d A s c i i d o c t o r . c o n v e r t _ f i l e ' s a m p l e ­ w i t h ­ s h o u t ­ b l o c k . a d o c '
85. 更多…… http://asciidoctor.org/docs/asciidoc-writers-guide/ http://asciidoctor.org/docs/user-manual/
86. ASCIIDOCTOR
87. 跨平台 Asciidoctor AsciidoctorJ (via JRuby) Asciidoctor.js (via Opal)
88. 1 → N HTML PDF EPUB Reveal.js LaTex Diagram
89. ASCIIDOCTOR (HTML) $ a s c i i d o c t o r i n d e x . a d o c
90. THEMES http://themes.asciidoctor.org/
91. ASCIIDOCTOR-PDF $ g e m i n s t a l l ­ ­ p r e a s c i i d o c t o r ­ p d f $ a s c i i d o c t o r ­ p d f i n d e x . a d o c
93. CJK 补丁和字体 $ g e m i n s t a l l a s c i i d o c t o r ­ p d f ­ c j k ­ k a i _ g e n _ g o t h i c $ a s c i i d o c t o r ­ p d f ­ c j k ­ k a i _ g e n _ g o t h i c ­ i n s t a l l $ a s c i i d o c t o r ­ p d f ­ r a s c i i d o c t o r ­ p d f ­ c j k ­ k a i _ g e n _ g o t h i c \ ­ a p d f ­ s t y l e = T H E M E \ i n d e x . a d o c
94. PROGIT2 中文版
95. ASCIIDOCTOR-EPUB3 $ g e m i n s t a l l ­ ­ p r e a s c i i d o c t o r ­ e p u b 3 $ a s c i i d o c t o r ­ e p u b 3 i n d e x . a d o c
98. MOBI $ g e m i n s t a l l k i n d l e g e n $ a s c i i d o c t o r ­ e p u b 3 ­ a e b o o k ­ f o r m a t = k f 8 i n d e x . a d o c
99. Asciidoctor Book Template $ g i t c l o n e h t t p s : / / g i t h u b . c o m / c h l o e r e i / a s c i i d o c t o r ­ b o o k ­ t e m p l a t e . g i t b o o k n a m $ c d b o o k n a m e $ b u n d l e i n s t a l l $ a s c i i d o c t o r ­ p d f ­ c j k ­ k a i _ g e n _ g o t h i c ­ i n s t a l l $ r a k e b u i l d
100. ASCIIDOCTOR-REVEAL.JS
101. $ g e m i n s t a l l a s c i i d o c t o r t i l t t h r e a d _ s a f e $ g e m i n s t a l l s l i m ­ ­ v e r s i o n 2 . 1 . 0 $ g i t c l o n e g i t : / / g i t h u b . c o m / a s c i i d o c t o r / a s c i i d o c t o r ­ r e v e a l . j s . g i t $ a s c i i d o c t o r ­ T t e m p l a t e s / s l i m i n d e x . a d o c
102. = T i t l e S l i d e = = S l i d e O n e * F o o * B a r * W o r l d = = S l i d e T w o H e l l o W o r l d ­ G o o d B y e C r u e l W o r l d
103. ASCIIDOCTOR-LATEX $ g e m i n s t a l l ­ ­ p r e a s c i i d o c t o r ­ l a t e x # 解析文档中的 l a t e x $ a s c i i d o c t o r ­ l a t e x ­ b h t m l f o o . a d o c # 生成 l a t e x 文档 $ a s c i i d o c t o r ­ l a t e x f o o . a d o c
104. \ [ e ^ { 2 \ p i \ s q r t { ­ 1 } } = 1 \ ]
105. ASCIIDOCTOR-DIAGRAM $ g e m i n s t a l l ­ ­ p r e a s c i i d o c t o r ­ d i a g r a m
106. [ d i t a a ] . . . . + ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ + | A s c i i d o c t o r | ­ ­ ­ ­ ­ ­ ­ + | d i a g r a m | | + ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ + | P N G o u t ^ | | d i t a a i n | | v + ­ ­ ­ ­ ­ ­ ­ ­ + + ­ ­ ­ ­ ­ ­ ­ ­ + ­ ­ ­ ­ + / ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ \ | | ­ ­ + A s c i i d o c t o r + ­ ­ > | | | T e x t | + ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ + | B e a u t i f u l | | D o c u m e n t | | ! m a g i c ! | | O u t p u t | | { d } | | | | | + ­ ­ ­ + ­ ­ ­ ­ + + ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ + \ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ / : ^ | L o t s o f w o r k |
107. $ a s c i i d o c t o r ­ r a s c i i d o c t o r ­ d i a g r a m i n d e x . a d o c
108. 总结
109. Markdown AsciiDoc
110. Jekyll Middleman
111. GitBook Asciidoctor
112. 快乐写作，快乐编程。
113. 谢谢。 by 黄增光（@chloerei） chloerei@gmail.com