我对文档要求不是非常高。但是有时候确实需要写技术相关的文档，比如设计方案，使用说明之类的。1. 要最终生成pdf。2. 支持贴代码。3.支持贴图片。
各位有什么建议么？有什么emacs插件或者其他此类文档工具？你们都用啥写文档？
DocBook xslTNG，用 Emacs 的 nxml-mode 写 XML，装了 rnc 语法文件就能开箱用。
用 paged CSS media publisher 生成 PDF
CSS publisher 不一定要用收费的，开源的比如 Samples | Vivliostyle 效果就已经很好了，也支持中文(好像就是传说中日本人边给 W3C 加草案边做的 CSS publisher)。
哪怕不用 DocBook, 用 Org, Markdown, AsciiDoc … 基本上想要生成像模像样的的 PDF 最好也是用 CSS publisher。给 LaTeX 编写好看的模版和用 CSS 设计文档难度差距实在大太，光是如何用 TeX 处理中文就够很多不善长折騰的人头大了
2 个赞
docbook 用着方便么？我不需要非常精美非常专业达到电子书或者论文级别的。所以简单的更合适。
Emacs的话，可以用org-mode。但我一般就用Microsoft Word 为主，主要为了和其他人共享，方便review。自己用的话，我就用一个mac系统自带的note，方便不同设备之间的同步。这几个选项也都可以导出pdf。
org我之前用过很久，做笔记。但是没用来弄过对外的pdf文档。后来不怎么用了。
markdown呢这个生成pdf技术文档怎么样？
mac 自带的不是page么？note是哪个？我怎么没印象。
- 因为有Emacs，我基本会优先考虑org，如果要用markdown的话。但markdown 导出pdf 应该比较常见，我用的少，不清楚你说的怎么样是啥意思，也许你可以自己玩玩看看。
- page 是对标 microsoft word的，note 是自带的应用: Notes，比较简单。
1 个赞
不方便，只有很少人能接受用 Emacs 写 XML，优点在于对技术向内容描述非常丰富，容易扩展，并且可以边写边验证格式。
AsciiDoc 相对容易写，而且相对技术文档有足够丰富的词汇。
Markdown 想实现复杂点的排版功能就要内嵌 HTML
不讲究的话生成 HTML 以后用浏览器导出 PDF 也差不多了，大部分用 JS 实现的 CSS publisher 本质上也就是在浏览器打印出 PDF 的时候美化一下。
3 个赞
我考虑先试试org或者markdown。输出pdf只要基本的，贴代码，配置，图片之类的就大致能满足我的需要了。
那我可用先试试 markdown，不行的话asciidoc。或者再找功能多的。
我曾经在vim里用asciidoc写文档很长一段时间，但自从用emacs orgmode之后就再也回不去了，写的时候基本不需要考虑格式调整，效率之高无与伦比。orgmode写完可以转成word或PDF，格式基本不需要调整就满足普通技术文档要求。当然转换过程应该是需要安装想tex/latex相关工具链的，我的经验是在linux下工具链安装是相对方便的
1 个赞
多谢，回头我也试试。我记着好几年前折腾过org转pdf。当时有点麻烦，最后没继续折腾了。
之前用org agenda做笔记和事项提醒很久。后来没办法和手机同步，就撂下不用了。
我倒是建议用latex。专业的事情要专业的软件来做。org-mode语法对中文的markdown先天不足。我以前尝试过org-mode写技术文档，总是不满意这里或那里平白插入的空格。所以，最终还是回归latex写文档。
用latex的好处是：1.写中文文档比org-mode要顺畅多了，不用担心一个M-Q多出一堆无谓的空格；2. 更灵活的表格（org-mode的表格限制太多）；3. 现成的中文文档模板（CTEX）；4. 丰富的CTAN库，可以满足你大部分的额外排版需求。
花些时间熟悉一下latex，CTEX，CTAN，写文档会越来越得心应手的。
估计你是用的比较早版本的 Org，差不多 2020 年以后中文支持改进得没啥问题了。更何况 Org 也能导出 LaTeX。
我自己是 plainTeX 用户。个人来说不喜欢 LaTeX，因为它假装自己是结构化语法，好像只要换个模版就能改样式，实际上对我这种对排版要求接近强迫症的人来说根本没做到样式和内容的分离。所以我单纯把 TeX 当排版引擎，DocBook XML 写完之后 XSLT 到 TeXML，再手动改 overflow 之类的问题。但除非是有大量公式的内容和对排版质量要求比较高汉字直排才是 TeX/upTeX 强项，其他情况用 CSS publisher 之类的方案对我来说方便许多。
反正以我自己的标准已经没法当正常人参考了。
哈哈，直接用plainTeX， 太牛了。LaTeX的语法，我看得都有些头大。 那你有尝试过GNU TeXmacs么？这个所见即所得，同时兼顾排版的编辑器，你觉得如何？我用过一段时间，还不错，但没有深入学习下去，不知道怎么搭配LaTeX模版，后面就直接去写LaTeX了，毕竟在Emacs里，写LaTeX 还挺享受的，有预览。
我不怎么用 GUI 编辑器的。TeXmac 和 TeX 只有名字上和用的排版算法的关系，代码是全然不同的，当然不能直接运行 LaTeX 模版，导入 LaTeX 功能只是把 LaTeX 当成一种 markup 处理以后转換格式。
你可以问问 @sadhen ，他开发的墨干是 TeXmacs 的 fork
2 个赞
多谢！那我就老老实实用Emacs，在里面写LaTeX等就可以了。sadhen 的工作我有了解，很佩服大神可以自己打造编辑软件。不过，我目前倾向于live in Emacs，就先不折腾其他软件了。
写技术文档没听说用latex的。latex主要是学术写作发表期刊/会议使用吧。而且latex只能导出pdf，而实际使用中导出html也是很常见的。
给几个 data point： emacs 官方文档 使用 texinfo 来写文档。orgmode 官网的文档使用 orgmode 写就。我常使用的 R 语言的包的文档通常都是配合 roxygen 这个工具直接使用 markdown 语法写就。
顶 AsciiDoc，语法相对简洁，也可以写代码扩展。如果在 Emacs 支持力度大的话，跟 org 也不是不能比。技术文档很多都开始用 AsciiDoc 了，我基本写东西都是 AsciiDoc 了，然后转成 epub，很少转成 PDF，当然排版没有那么好，够用就行。
我得从比较专业的角度指出 LaTeX 的一个重大问题:
如果 LaTeX 更新版本(到 3e)了，旧的文档编译不过了怎么办？
因为 LaTeX 从 2 更新到 2e 就发生了这种事，Common Lisp The Language 的公开 PDF 有一处排版问题，我一直想修复。
但虽然 CLtL 的 LaTeX 代码是公开的，因为用的是旧的 LaTeX 2，早就没法编译了。
重构？总共 6 万行的文件，里面还尽是这样的自定义宏。
\begin{lisp}
;;; Create a one-dimensional array of five elements. \\*
(make-array 5) \\
\\
;;; Create a two-dimensional array, 3 by 4, with four-bit elements. \\*
(make-array '(3 4) \cd{:element-type} '(mod 16)) \\
\\
;;; Create an array of single-floats.\\*
(make-array 5 \cd{:element-type} 'single-float)) \\
\\
;;; Making a shared array. \\*
(setq a (make-array '(4 3))) \\
(setq b (make-array 8 :displaced-to a \\*
~~~~~~~~~~~~~~~~~~~~~~:displaced-index-offset 2)) \\
;;; Now it is the case that: \\*
~~~~~~~~(aref b 0) \EQ\ (aref a 0 2) \\*
~~~~~~~~(aref b 1) \EQ\ (aref a 1 0) \\*
~~~~~~~~(aref b 2) \EQ\ (aref a 1 1) \\*
~~~~~~~~(aref b 3) \EQ\ (aref a 1 2) \\*
~~~~~~~~(aref b 4) \EQ\ (aref a 2 0) \\*
~~~~~~~~(aref b 5) \EQ\ (aref a 2 1) \\*
~~~~~~~~(aref b 6) \EQ\ (aref a 2 2) \\*
~~~~~~~~(aref b 7) \EQ\ (aref a 3 0)
\end{lisp}
用 plainTeX 有这问题吗？不好意思，DEK 早早就冻结了 TeX，为的就是換了不同的电脑，不同的操作系统，还能编译出一样的结果。
把要长久留存的文档用一个没有固定标准的格式，绝对不是什么明智的选择。
如果当年用 DocBook 写的，想要換到最新版本就是跑一下 XSLT 的事。
我看了各位的介绍。目前也倾向于先试试asciidoc。org我比较担心万一要和其他人共享编辑文档，他们会抓瞎。
你说的排版没那么好，能具体介绍一下么？或者你写的文档如果是公开的，能否给个下载链接看看。