[AsciiDoc]_[项目管理]_[适合写书写需求文档的纯文本轻量级标记语言]

场景

  1. markdown适合写短篇文章,但是不适合写书,需求文档这类复杂多页的文档。有什么文本格式适合写需求文档呢?并且能生成PDF或者docx格式方便阅读?

说明

  1. 在阅读gradleuserguidePDF文档时,发现它是使用Asciidoctor生成的,生成的文档整齐,美观,还有书签。之后了解了一下asciidoc格式和markdown的不同。

  2. 之前说过需求文档最好使用纯文本的文档格式编写,这样可以多人协作。使用二进制格式word不适合进行版本管理(使用svn,git). markdown由于它没有包含外部文件语法和不方便生成其他格式文档(PDF),并不适合写需求文档。

  3. 关于asciidoc的语法,参考官方文档asciidoc语法

asciidoc的优点

  1. 支持include外部的.adoc文件,这样就可以分章节写书。比如写复杂的需求文档,写一个操作手册或语言总结。

  2. 支持复杂丰富的纯文本书写格式。

  3. 一个完善的文本处理和转换工具链,可以转换为HTML,ePub,PDF,DocBook等.

安装和使用

  1. 下载RubyWindows版本.
    ruby Windows安装包

  2. 安装asciidoctor,安装完Ruby之后新打开一个命令行窗口。

$ gem install asciidoctor
  1. adoc转换为pdf,需要安装asciidoctor-pdf.
$ gem install asciidoctor-pdf
  1. 验证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)
  1. 安装源码语法高亮支持.
gem install rouge
  1. 安装VSCodeasciidoc文档扩展编辑支持,搜索扩展AsciiDoc,作者是asciidoctor.

图1:
在这里插入图片描述

例子

  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 click

class MyContentHandler(ContentHandler):

    def startElement(self, name, attrs):
        self.elementName = name
        self.elementAttrs = attrs
        self.isElementStart = True
        self.elementConent = ""

    def endElement(self, name):
        self.elementName = name
        self.isElementStart = False
        
    def characters(self, content):
        if content != None:
            self.elementConent = content

def 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 = 1024
    if maxBuf > offset:
        maxBuf = offset
    
    pos = 0
    line = ""
    while pos < offset:
        if (pos + maxBuf) > offset:
            maxBuf = offset - pos
        line = file.readline(maxBuf)
        pos = pos + maxBuf
    return 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 = 1
        maxBuf = 1024
        line = ""
        while n < lineNumber:
            n = n +1
            lineEnd = False
            while not lineEnd:
                line = f.readline(maxBuf)
                # print(line)
                a = line[-1:]
                if a == "\n":
                    lineEnd = True
                    break
        
        # 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查看帮助\n
    XmlValidator --path XML路径""")
@click.option('--path',default="",help="XML文件路径") 
@click.pass_context 
def parseFile(ctx,path):
    
    if(len(path) == 0):
        print("请输入有效XML路径!")
        return

    parser = 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():
    return

if __name__ == "__main__":
    print("Begin Parse!")
    parseFile(obj={})  
    print("End Parse!")
    pass
----

class-1.adoc

  1. 放在test.adoc的同目录的others子目录下,即others/class-1.adoc,用来测试包含文件功能的.

build.bat

set GEM_FONTS_DIR="C:/Windows/Fonts"
asciidoctor-pdf -a scripts=cjk -a pdf-theme=./cjk-theme.yml -a pdf-fontsdir=GEM_FONTS_DIR,%GEM_FONTS_DIR% test.adoc

cjk-theme.yml

  1. asciidoctor-pdf所需要的样式文件,主要是用来配置支持的中文字体。
extends: default
font:
  catalog:
    merge: true
    KaiGen Gothic CN:
      normal: KaiGenGothicCN-Regular.ttf
      bold: KaiGenGothicCN-Bold.ttf
      italic: KaiGenGothicCN-Regular-Italic.ttf
      bold_italic: KaiGenGothicCN-Bold-Italic.ttf
  fallbacks:
  - 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

  1. 调用asciidoctor-pdf的批处理脚本。
@echo off
set GEM_FONTS_DIR="C:/Windows/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

安装字体

  1. 下载开源商业免费的思源黑体。复制到C:\Windows\Fonts下。在调用asciidoctor-pdf时会用到。

目录结构

│  build.bat
│  cjk-theme.yml
│  test.adoc
│  test.pdf
└─others
        class-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

思源黑体

已标记关键词 清除标记
©️2020 CSDN 皮肤主题: 创作都市 设计师:CSDN官方博客 返回首页
实付 9.90元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值