从 Word 到 Docbook, 最后用 Pandoc, 让程序员爱上写文档

写文档一直是程序员非常讨厌的工作, 甚至和改需求一样令人厌烦. 在程序员眼里比写程序还难, 即便强制执行下来文档质量也很难让人满意.

相信大多数公司写文档都是用 Word, 笔者也是用了 Word 写了好几个项目的文档. 架构, 设计, 运维等好几份, 呵呵, 即便是写的再好, 交给客户也基本是不看的. 一个文档是项目组内好几个成员编写的, 大家各写各的模块, 各自的实现, 然后一起合并, 合并时修改字体, 字号, 目录等, 第一次合并还好, 再升级几个版本后, 大家改了哪里, 没改哪里, 根本看不出来.

于是我就开始找一些文档工具. 个人一直看 Spring 的项目文档, Pdf 格式和在线 Html 格式都写的非常漂亮. 相信大家都很熟悉. 如下:

于是锁定了 Docbook 这个文档工具. Docbook 是支持 Maven 的, 在 pom 的 plugins 中加上支持 Docbook 的 plugin.

’’’

<plugin>
            <groupId>org.jboss.maven.plugins</groupId>
            <artifactId>maven-jdocbook-plugin</artifactId>
            <version>2.3.8</version>
            <extensions>true</extensions>
            <dependencies>
                <dependency>
                    <groupId>org.jboss</groupId>
                    <artifactId>jbossorg-docbook-xslt</artifactId>
                    <version>1.1.1</version>
                </dependency>
                <dependency>
                    <groupId>org.jboss</groupId>
                    <artifactId>jbossorg-jdocbook-style</artifactId>
                    <version>1.1.1</version>
                    <type>jdocbook-style</type>
                </dependency>
                <dependency>
                    <groupId>org.jboss.jdocbook</groupId>
                    <artifactId>jdocbook-core</artifactId>
                    <version>1.0.7</version>
                    <exclusions>
                        <exclusion>
                            <groupId>net.sf.docbook</groupId>
                            <artifactId>docbook-xml</artifactId>
                        </exclusion>
                        <exclusion>
                            <groupId>net.sf.docbook</groupId>
                            <artifactId>docbook-xsl</artifactId>
                        </exclusion>
                    </exclusions>
                </dependency>
                <dependency>
                    <groupId>net.sf.docbook</groupId>
                    <artifactId>docbook-xml</artifactId>
                    <type>pom</type>
                    <version>5.0</version>
                </dependency>
                <dependency>
                    <groupId>net.sf.docbook</groupId>
                    <artifactId>docbook-xsl</artifactId>
                    <type>pom</type>
                    <version>1.76.1</version>
                </dependency>
            </dependencies>
            <executions>
                <execution>
                    <id>tutorial_zh_CN</id>
                    <phase>package</phase>
                    <goals>
                        <goal>resources</goal>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <sourceDocumentName>index.xml</sourceDocumentName>
                        <masterTranslation>zh-CN</masterTranslation>
                        <sourceDirectory>${basedir}/src/main/docbook</sourceDirectory>
                        <fontsDirectory>${basedir}/src/main/fonts</fontsDirectory>
                        <imageResource>
                            <directory>${basedir}/src/main/docbook</directory>
                        </imageResource>
                        <cssResource>
                            <directory>${basedir}/src/main/docbook</directory>
                        </cssResource>
                        <formats>
                            <format>
                                <formatName>html</formatName>
                                <stylesheetResource>file:${basedir}/src/main/resources/xhtml.xsl
                                </stylesheetResource>
                                <finalName>index.html</finalName>
                            </format>
                            <format>
                                <formatName>html_single</formatName>
                                <stylesheetResource>file:${basedir}/src/main/resources/xhtml-single.xsl
                                </stylesheetResource>
                                <finalName>index.html</finalName>
                            </format>
                            <format>
                                <formatName>pdf</formatName>
                                <stylesheetResource>file:${basedir}/src/main/resources/pdf.xsl</stylesheetResource>
                                <finalName>${project.name}-zh_CN-${project.version}.pdf</finalName>
                            </format>
                        </formats>
                        <options>
                            <xincludeSupported>true</xincludeSupported>
                            <autoDetectFonts>true</autoDetectFonts>
                        </options>
                    </configuration>
                </execution>
            </executions>
        </plugin>

’’’
然后组织好文档目录结构, 就可以生成各种格式的文档的了. 编写的文档是 xml 格式, 能使用文本对比工具做对比. 文档也被拆分成很多章节, 成员各编辑各的章节, 管理也方便许多, 直接在项目目录下建个 Maven 项目, 项目内存放这些文档.

但是, docbook 语法着实让大家都头疼, 我学习了一遍不要紧, 大家都学习一遍. 文档中夹杂大量的 xml 标记, 加个图片, 加个段落, 加个列表等非常麻烦. 困难的是有时候加个图片生成 pdf 已经超出 pdf 显示范围了.

在 github 上看到有人用 ascii-doc 写开源翻译文档, 语法是 markdown 格式, 而且能生成各种格式. 我边尝试了一把, 起初还以为是 Maven 的 plugin, 找了很久没找到这样的 plugin. 无果. 无意中发现了 pandoc 这个工具, 编写文档可以使用 markdown, 简单的 pandoc 命令就能生成 html, epub, word, pdf 等格式, 我深深的被吸引. 我用的 Mac, 安装这类软件很麻烦, 网上说需什么 brew, 或者源码编译安装. 几次尝试都不成功, 试了很久就想放弃. 但是最后在一个 blog 中发现一个连接, 终于下载到了 pandoc 的 OS X 的安装包. 花了很大力气, 不敢独享, 分享给大家: http://pan.baidu.com/s/1c0fJ01i | pandoc-1.9.4.2.dmg

Pandoc 确实是文档的终结者, 能把 txt, word, pdf, docbook, markdown 等格式相互转换. 其实他们相互转换还是有些兼容性问题的. 但是只要能把 markdown 格式转成任意格式, 那就是最重要的功能.
如把 markdown 转成 html 命令:
pandoc -f markdown -o readme.html readme.md

  • -f 来源的格式
  • -o 输出到文件

输出也可以用一个 css 把网页修饰的更漂亮一点. 可以加 -c style.css 等等.

如要转成word 格式, 可以使用命令:

pandoc -f markdown -o readme.docx readme.md

如你所见, pandoc 可以用 -o 指定的文件的后缀来确定你要输出的是什么格式. pandoc 转成 pdf 需要latex支持, 并且对中文支持需要在命令行指定中文编码字符集:

pandoc -f markdown -o readme.pdf --latex-engine=xelatex -V  mainfont="SimSun" readme.md

在生成 word, pdf, html 时, 也仍然可以使用 -c 加上一个 css 参数来控制让文档更美观一些.

下面是 pandoc 命令行:

pandoc --help
pandoc [OPTIONS] [FILES]
Input formats:  native, json, markdown, markdown+lhs, rst, rst+lhs, docbook,
            textile, html, latex, latex+lhs
Output formats: native, json, html, html5, html+lhs, html5+lhs, s5, slidy,
            slideous, dzslides, docbook, opendocument, latex, latex+lhs,
            beamer, beamer+lhs, context, texinfo, man, markdown,
            markdown+lhs, plain, rst, rst+lhs, mediawiki, textile, rtf, org,
            asciidoc, odt, docx, epub
Options:
  -f FORMAT, -r FORMAT  --from=FORMAT, --read=FORMAT
  -t FORMAT, -w FORMAT  --to=FORMAT, --write=FORMAT
  -o FILENAME           --output=FILENAME
                    --data-dir=DIRECTORY
                    --strict
  -R                    --parse-raw
  -S                    --smart
                    --old-dashes
                    --base-header-level=NUMBER
                    --indented-code-classes=STRING
                    --normalize
  -p                    --preserve-tabs
                    --tab-stop=NUMBER
  -s                    --standalone
时间： 2024-10-15 16:35:00

从 Word 到 Docbook, 最后用 Pandoc, 让程序员爱上写文档的相关文章

Java POI Word 写文档

package apache.poi; import java.io.ByteArrayInputStream;import java.io.ByteArrayOutputStream;import java.io.File;import java.io.FileInputStream;import java.io.FileOutputStream;import java.io.IOException;import java.io.OutputStream;import java.util.Ha

怎样将pdf转换成word文档

怎样将pdf转换成word文档 从事办公文书的同学唠叨最近一段时间都在烦恼同一个问题,就是有大量的PDF文档需要操 作,工作量大的时候,忙得焦头烂额,甚至要还得加班才能赶完.当面对数量大的文档需要转换时,你该怎么办?小编给你推荐一款叫迅捷PDF转换成Word转 换器,简单的操作,就可以把文档完美转换哦,一起来看看怎么转换吧! PC版迅捷PDF转换成Word转换器: 这是一款操作简单,使用方便,效果极好的PDF转换成Word转换器工具,使用它,您可以将一个或多个文件PDF文件转换成想要的文本格式,

asp.net如何实现word文档在线预览

原文:asp.net如何实现word文档在线预览 实现方式:office文档转html,再在浏览器里面在线浏览 1.首先引入com组件中office库,然后在程序集扩展中引入word的dll 2.将Microsoft.Office.Interop.Word的嵌入互操作类型设置为 false,如图 3.主要代码 C# 代码   复制 using System; using System.Collections.Generic; using System.Linq; using System.Web

将PDF文件转换为word文档格式

平常编辑修改一些文档都是office类型的文档,但是随着PDF文件应用越来越广泛,在处理文档的时候遇见PDF也是很常见的虽然已经有PDF的编辑工具,但是对文档内容进行大范围的修改还是很不方便的,一般我们编辑文档都是用word来编写.即使是要支持PDF文档可以用word制作好以后在输出PDF格式,那么怎样把PDF文件转换成为word呢? 常用的办公文档之间的格式互相转换可以通过文档转换工具来实现,对于经常要处理各种文档的可以安装转换工具进行转换,如果只需要转换一些小文档,那么直接通过在线转换方式也

如何将PDF文件转换成word文档格式

以前看一些视频的时候,视频文件会有很多种格式,因为格式播放问题经常会需要转换这些格式.于此相同,现在的一些文档格式的类型也有很多种,有时为了方便应用也会需要转换成不同的文档格式,如何将PDF文档转换成word就是常需要应用到的. 很多文档格式都可以保存输出成PDF文件格式,相同的,将PDF格式也可以转换成其他的文档类型.例如我们常见的一些word,ppt,Excel以及图片文件.并且大部分文档之间也可以进行格式转换.?a.文档格式的转换也是有对应的转换工具的.可以先安装PDF转换器并打开.把PD

c#中操作word文档-二、比较全的一份示例

最近两天研究了一下如何使用VS2008(C#语言)输出Word文档.以下是几点总结: 1.非常简单. 2.开发及运行环境要求.操作系统为:WindowsXP(安装.net framework2.0)/Vista/Win7:在操作系统必须安装Word2003完全安装版.这里必须要强调是Word2003完全安装版,因为软件开发及运行都需要一个com组件:Microsoft word 11.0 Object Library.如果不是Word2003完全安装版,可以下载这个com组件,并手动的安装这个c

CA证书应用三：给Word/Excel文档添加数字签名

本期介绍CA证书另外一个应用:给Word/Excel文档添加数字签名. 当我们完成一篇Word文档或者一个Excel表格后,如果希望该文档或者Excel表格不再被别人修改,那么此时可以给文档或者Excel表格加上自己的数字签名.具体步骤如下: 一.准备工作 1.自己的数字证书,一般为CA中心颁发的UKey: 2.已经完成的Word文档(或者Excel表格). 二.添加签名 1.打开要签名的文档,如下图中的测试文档: 2.将UKey接入PC,选择Word的"文件"-〉"保护文档

利用Aspose.Words处理Word文档之间的转换和内容操作

一.概述:Aspose.Words是一个商业.NET类库,可以使得应用程序处理大量的文件任务.Aspose.Words支持Doc,Docx,RTF,HTML,OpenDocument,PDF,XPS,EPUB和其他格式.使用Aspose.Words可以在不使用Microsoft.Word的情况下生成.修改.转换和打印文档.二.功能简介:1.Aspose.Words具有高质量的文件格式转换功能,可以和Doc,OOXL,RTF,TXT等格式互相转换.2.通过丰富的API以编程方式访问所有的文档元素和

Mac word文档的消失问题以及解决方案

最近用mac电脑上的Microsoft Word写文档时,出现一个很奇怪的现象:明明我已经保存了文档到某个目录下,但是当我退出Word后,准备去保存目录找文档时发现文档消失了,前一秒还在!!! 通过各种搜索,终于找到了解决方案: 在命令行终端上运行:sudo find /private/var/folders -name "*.tmp" -type f | grep "Word",如果提示输入密码,密码就是登录电脑的密码 运行命令后,可以看到类似上图中标红的几个tm