場景

markdown適合寫短篇文章，但是不適合寫書，需求文檔這類復雜多頁的文檔。有什么文本格式適合寫需求文檔呢？并且能生成PDF或者docx格式方便閱讀？

說明

在閱讀gradle的userguide的PDF文檔時，發現它是使用Asciidoctor生成的，生成的文檔整齊，美觀，還有書簽。之后了解了一下asciidoc格式和markdown的不同。

之前說過需求文檔最好使用純文本的文檔格式編寫，這樣可以多人協作。使用二進制格式word不適合進行版本管理（使用svn,git）. markdown由于它沒有包含外部文件語法和不方便生成其他格式文檔(PDF)，并不適合寫需求文檔。

關于asciidoc的語法，參考官方文檔asciidoc語法。

asciidoc的優點

支持include外部的.adoc文件,這樣就可以分章節寫書。比如寫復雜的需求文檔，寫一個操作手冊或語言總結。

支持復雜豐富的純文本書寫格式。

一個完善的文本處理和轉換工具鏈，可以轉換為HTML,ePub,PDF,DocBook等.

安裝和使用

下載Ruby的Windows版本，取目前最新版的64位版本rubyinstaller-3.1.2-1-x64.exe
ruby Windows安裝包

安裝完Ruby之后新打開一個命令行窗口, 安裝asciidoctor。

$ gem install asciidoctor

把adoc轉換為pdf，需要安裝asciidoctor-pdf.

$ gem install asciidoctor-pdf

驗證asciidoctor-pdf安裝完成

C:\Users\apple>asciidoctor-pdf -v Asciidoctor PDF 1.5.3 using Asciidoctor 2.0.10 [https://asciidoctor.org] Runtime Environment (ruby 2.6.6p146 (2020-03-31 revision 67876) [x64-mingw32]) (lc:GBK fs:GBK in:UTF-8 ex:UTF-8)

安裝源碼語法高亮支持.

gem install rouge

安裝VSCode的asciidoc文檔擴展編輯支持，搜索擴展AsciiDoc,作者是asciidoctor.

圖1:

例子

以下文件自行保存為對應的文件名.

test.adoc

= 等號作為文檔標題== Level 1 Section Title=== Level 2 Section Title== 包含外部的adoc文檔 include::others/class-1.adoc[]== ASCDOc *hello**hello*== ASCDOc232中文我的博客地址是https://blog.csdn.net/infoworld**我的博客地址是https://blog.csdn.net/infoworld**我的博客地址是https://blog.csdn.net/infoworld== 常文本 Paragraphs don't require any special markup in AsciiDoc.A paragraph is just one or more lines of consecutive text.To begin a new paragraph, separate it by at least one blank line. Newlines within a paragraph are not displayed.== 超鏈接https://asciidoctor.org[Asciidoctor]== markdown語法== ruby代碼 [[app-listing]] [source,ruby] .app.rb ---- require 'sinatra'get '/hi' do"Hello World!" end ----== Python多行代碼.XmlValidator.py [source,python] ----from io import SEEK_CUR, SEEK_SET from xml.sax.handler import ContentHandler from xml.sax import SAXParseException, make_parser import clickclass MyContentHandler(ContentHandler):def startElement(self, name, attrs):self.elementName = nameself.elementAttrs = attrsself.isElementStart = Trueself.elementConent = ""def endElement(self, name):self.elementName = nameself.isElementStart = Falsedef characters(self, content):if content != None:self.elementConent = contentdef printElement(elementName,isStartElement,elementAttris,elementContent):print("[<",end="")if not isStartElement:print("/",end="")print(elementName,end="")if(elementAttris != None):for key,value in elementAttris.items():print(" "+key+"="+value,end=" ")print(">",end="")if(elementContent != None):print(elementContent,end="")print("]")def charSeek(file,offset,maxOffsetLength):maxBuf = 1024if maxBuf > offset:maxBuf = offsetpos = 0line = ""while pos < offset:if (pos + maxBuf) > offset:maxBuf = offset - posline = file.readline(maxBuf)pos = pos + maxBufreturn line[-maxOffsetLength:]def readFileLineColumnContext(fileName,lineNumber,columnNumber,maxOffsetLength):# print("[File:%s]-[Line:%d]-[Column:%d]-[MaxOffsetLength:%d]" # % (fileName,lineNumber,columnNumber,maxOffsetLength))with open(fileName,encoding="utf-8") as f:n = 1maxBuf = 1024line = ""while n < lineNumber:n = n +1lineEnd = Falsewhile not lineEnd:line = f.readline(maxBuf)# print(line)a = line[-1:]if a == "\n":lineEnd = Truebreak# f.seek是針對字節的,不要使用,不然如果位置在一個多字節字符的中間,read解碼utf-8字符會報錯.preLine = charSeek(f,columnNumber,maxOffsetLength)b1 = f.read(maxOffsetLength)print("-->前一行:"+line[-maxOffsetLength:],end="")print("-->當前行:" +preLine+b1)pass@click.command(help="""校驗XML格式完整性,請使用--help查看幫助\nXmlValidator --path XML路徑""") @click.option('--path',default="",help="XML文件路徑") @click.pass_context def parseFile(ctx,path):if(len(path) == 0):print("請輸入有效XML路徑!")returnparser = make_parser()handler1 = MyContentHandler()parser.setContentHandler(handler1)try:parser.parse(path)except SAXParseException as e:print("-->解析錯誤: ["+str(e)+"]")print("-->解析起始元素上下文-1: ",end="")printElement(handler1.elementName,handler1.isElementStart,handler1.elementAttrs,handler1.elementConent)readFileLineColumnContext(path,e.getLineNumber(),e.getColumnNumber(),20)def test():returnif __name__ == "__main__":print("Begin Parse!")parseFile(obj={}) print("End Parse!")pass ----

class-1.adoc

放在test.adoc的同目錄的others子目錄下,即others/class-1.adoc,用來測試包含文件功能的.

class-1.adoc

cjk-theme.yml

asciidoctor-pdf所需要的樣式文件，主要是用來配置支持的中文字體。

extends: default font:catalog:merge: trueKaiGen Gothic CN:normal: KaiGenGothicCN-Regular.ttfbold: KaiGenGothicCN-Bold.ttfitalic: KaiGenGothicCN-Regular-Italic.ttfbold_italic: KaiGenGothicCN-Bold-Italic.ttffallbacks:- KaiGen Gothic CN base:font-family: KaiGen Gothic CN heading:font-family: $base-font-family abstract:title:font-family: $heading-font-family sidebar:title:font-family: $heading-font-family

build.bat

調用asciidoctor-pdf的批處理腳本。

@echo off set GEM_FONTS_DIR="D:\Fonts" asciidoctor-pdf -a source-highlighter=rouge -a scripts=cjk -a pdf-theme=./cjk-theme.yml -a pdf-fontsdir=GEM_FONTS_DIR,%GEM_FONTS_DIR% test.adoc pause

安裝字體

下載開源商業免費的思源黑體。復制到C:\Windows\Fonts下。在調用asciidoctor-pdf時會用到。注意，在 Win10由于權限問題安裝在C:\WIndows\Fonts是識別不了的，可以解壓到其他盤，比如D:\Fonts. 還有下載字體只需要4個

KaiGenGothicCN-Regular.ttf KaiGenGothicCN-Bold.ttf KaiGenGothicCN-Regular-Italic.ttf KaiGenGothicCN-Bold-Italic.ttf

目錄結構

│ build.bat │ cjk-theme.yml │ test.adoc │ test.pdf └─othersclass-1.adoc

運行

雙擊build.bat即可,等待一會生成test.pdf文件。
圖2

例子下載

https://download.csdn.net/download/infoworld/12940516

參考

ruby Windows安裝包

asciidoctor的官方地址

Asciidoctor 與 gradle 整合生成 PDF備忘

Asciidoctor Gradle Plugin

Asciidoctor Gradle Plugin Source

asciidoctor-pdf

asciidoc語法

KaiGenGothicCN-theme.yml

support-for-non-latin-languages

思源黑體

asciidoc中文參考

asciidoctor編輯工具

總結

以上是生活随笔為你收集整理的[AsciiDoc]_[项目管理]_[适合写书写需求文档的纯文本轻量级标记语言]的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。