[AsciiDoc]_[项目管理]_[使用AsciiDoctor-pdf作为需求文档生成工具的一些问题]

场景

1. 在之前的 适合写书写需求文档的纯文本轻量级标记语言 讲过使用asciidoctor写需求文档，可以通过版本控制来进行多人编辑目前来说还是可以的. asciidoctor的格式是adoc, 它也支持include外部的adoc文件，这样的好处就是不同版本需求可以合并到一个大需求文档里，或者只需要某个版本的需求文档也可以。

2. 使用asciidoctor-pdf模块来生成pdf格式，支持书签。可以通过命令来生成不同版本或总版本的pdf文件，还是不错的，PDF格式作为跨平台的格式，也可以方便在macOS里进行预览，不需要安装额外的第三方软件。

说明

1. 目前asciidoctor使用上也有一些不方便的问题。

1. 生成的PDF文件字体颜色的问题

1. 目前asciidoctor-pdf不支持针对某个字加特定颜色，比如#00ff00. 只有以下3种方法，可能以后版本更新后会有吧。

   1。通过主题加颜色。就是 cjk-theme.yml里针对特定的元素，比如标题，全局的。
   2。#very 中文 obvious# yes no. 通过#xxx#高亮背景色。
   3。`xxxx` 通过``高亮文本，目前是红色。
   

2. 生成HTML格式使用css样式.

1. asciidoctor-pdf不支持css样式文件，但是asciidoctor生成html就支持. 使用[.伪类]#xxxxx# 来对某些文字加颜色. 使用以下命令生成.

   asciidoctor -a stylesheet=cjk.css test.adoc
   

test.adoc

```
[.test]#hello# world
```

cjk.css

```
.test{color:#00ff00}
```

3. VSCode 预览显示asciidoctor自带样式，白底黑字更美观

1. 在菜单 文件-〉选项-〉设置, 之后再搜索框里输入asciidoctor. 把以下的Use Editor Style的勾去掉。

4. VSCode的预览无法显示图片。

1. 这是asciidoctor插件预览的一个BUG，目前还没解决。可以通过在adoc的文档开头加入以下属性解决.

   :data-uri: {docdir}
   

参考

1. Preview image does not display with relative path

2. Preview images don’t show if the folder name of the doucment starts with a number followed by a dot and a blank

3. asciidoctor-pdf/theming-guide.adoc at master · asciidoctor/asciidoctor-pdf · GitHub

4. Using Custom Inline Styles :: Asciidoctor Docs

5. Quotation Marks and Apostrophes :: Asciidoctor Docs

6. 适合写书写需求文档的纯文本轻量级标记语言

7. asciidoctor中文手册