JSON 腳本架構

架構概觀
.docogen 主要部份
.docogen 可延展部份
article 詳細功能介紹
- title
- priority
- content
  - data
    - none
    - text
    - list
    - table
    - formula
    - code
    - figure(inside, in data section)
    - web-restful-api
  - figure(outside, in same layer with data section)
  - subarticle

架構概觀

docoGen 的架構是由 JSON 格式所構成，並且其副檔名為 .docogen
而在版本 0.1.0 以後，系統上可支援 markdown 格式來做腳本格式支援
docoGen 可以分為兩個部份： 主要部份 以及 可延展部份
- 後面部份會為這些做詳細的介紹
完整的展示連結

// docoGen 的大架構如下：
{
    title: ... ,
    options: ...,
    author: [ ... ],
    article: [ ... ],
    reference: [ ... ]
}

主要部份

若你有多個 docogen 腳本檔案，則只需要有一個俱備這個部份即可

主要項目有：

title：整個文件的開頭標題
options：其他的一些對於文件的 config 設定
- type： LaTeX document type. 目前支援有 article、report、IEEEtran、proc
- version：（可有可無）此文件版本號

{
...
    title: "My Title",
    options: {
        type: "article",
        version: "0.0.1"
        , ...
    }
}

author: 該文件的作者，以及共同作者欄位（支援多個欄位）

{
...
    author: [
        {
            name: "author 1",
            email: "...",
            phone: "...",
            website: "..."
        }, ...
    ]
}

abstract: 開頭的簡介部份，採用 string array 的方式做使用

{
...
    /* using string array */
    abstract: [
        "sentence 1"
        ,"sentence 2"
        , ...
    ]
}

article[optional]：可延展的部份，數量不限，看使用者做加減（下面有詳細介紹）
reference[optional]：為 LaTeX 之後 Reference （a.k.a 延伸閱讀）地方

可延展部份

這些腳本內容跟上面不一樣，只有article存在
可以隨便放在目標資料夾底下的任何位置（比如想針對每個專案內資料夾做說明，可以放在該資料夾底下）
當你使用 docoGen 來產生 LaTeX 文件檔時，docoGen 會去收集位於目標專案資料夾下收集所有的 .docogen 檔案，並且可以依據 docogen 檔案裏面的 article 做合併；而由於這些分檔都是可延展部份，所以只有 article 這一個 array object 存在，docoGen 會依據該 article 的 priority 做排序，讓最後的文本可以依據你想要的模式來做排序
可延展部份的項目有：
- article: 為 array object，裝有多個文件檔
- reference: 使用 LaTeX 格式 \\cite{...(reference_name)} 在一般的字串中，便可以再文本中做到 LaTeX 支援的 cite 的功能！而 cite 的內容就放在這個部份（可以隨便放，之後也都會合併在一起）

詳細功能介紹

在這個部份，我們會展示 docogen 的詳細內容
並且隨著 docoGen 的更新，會持續更新再這裡

title

每個文章的開頭標題

priority

前面提到的，由於支援分檔，所以提供一個可以讓使用者對不同文章做到排序的功能
而 priority 的大小可以從負整數到正整數，不管如何，排序會從小排到大

content

每個 article 的 element 接會儲存其內容再這個項目，為 array object
透過 field name 來指定此 content 的標題
並且把主要內容存在 field data 的 array object 中（所以 data 內都為相同的格式）
由 field type 來指定該 data 內的格式
接下來就詳細介紹 type 的種類：

none

none: 單純做文字的增加

// content with "none"
{
    name: "content title",
    type: "none",
    data: [
        { info: "your word here" },
        { info: "..." }, ...
    ]
}

text

text: 為 unordered list 的格式，每個於 data 中的 element 都會是一個 unordered list item

// content with "text" (格式與 none type 相同)
{
    name: "content title",
    type: "text",
    data: [
        { info: "your word here" },
        { info: "..." }, ...
    ]
}

list

list: 支援 list 格式
- 每個 name 欄位表示 list 的內容
- 同一層 array 的 element 為同一層的 list
- 若要在某個 list 加上子項目，則使用 subitems 的 array object 來加入一層子項目；若沒有的話，則可以不需要加這項 subitmes 欄位
- e.g.
```
{
    name: "List 1",
    subitems: []
},{
    name: "List 2"
}
```

table

這邊是表格的使用，而使用方式為 docoGen 自訂義的方式
必要的欄位有：
- column 名稱
- table 名稱
- 每個 column 的值

{
    name: "content title",
    type: "table",
    data: [
        { 
             title: "Col 1 title",
             value: [ "Col-1-value1", "Col-1-value2", "Col-1-value3" ]
        },
        { ... }
    ]
}

formula

為數學式的支援
目前支援 4 種類型的表示方式：
- info: 穿插在數學式中的文字
- inline: inline 模式的數學表示；不換行，直接貼在文字後面的數學式
- display: display 模式的數學表示；會獨立一行，並採全欄位佔據呈獻
- equation: enclose by {equation} tag.
你也可以把 4 種同時寫在同一個 element 裡頭，則轉換時會採 info -> inline -> display -> equation 的順序做排序

{
    name: "content title",
    type: "formula",
    data: [
        { info: "normal sentence(doesn't contain any mathmetic equation)" },
        { inline: "math equation(with "( )"), e.g. \(x^2 + y^2 = z^2\) },
        { display: "math equation(with "[ ]"), e.g. \[ x^n + y^n = z^n \])" },
        { equation: "math equation(which will be enclose by \begin{equation} tag)" },
        // Merged format -> 
        {
           info: ...,
           display: ...
        }
    ]
}

code

為程式碼展示的支援，可以使用 2 種方式做引入程式碼的動作：
- 假如想使用檔案，則可以用 src 的欄位來指定檔案
  - 透過欄位 flag 來做 src 是否為相對(rel)、絕對(abs)路徑
- 若只是想單純秀一段程式碼，則可以使用 raw 的欄位來直接加入程式碼片段 (範例如下)

版本 0.1.3 後， src 也可以使用相對路徑做檔案引入！
注意： flag 的預設值為 rel (relative)

{
    name: "content title",
    type: "code",
    data: [
        { 
             // Type 1
             lang: "your language (e.g. C, C++, matlab, ... etc)",
             caption: "your caption about the following instance",
             src: "the absolute path to your code"
        },
        { 
             // Type 2
             lang: "your language (e.g. C, C++, matlab, ... etc)",
             caption: "your caption about the following instance",
             raw: "put your code content directly"
        },
        { 
             // Type 3 (relative usage)
             lang: "your language (e.g. C, C++, matlab, ... etc)",
             flag: "rel"
             caption: "your caption about the following instance",
             src: "the relative path to your code"
        },
        { ... }
    ]
}

figure

這個 figure 是放在 content 內的部份，另外還有跟 content 同一層的（提供給 article 做使用的），提高對於圖片排版需求
一樣為 array object，可以放多張圖片
支援相對/絕對路徑（在 Window 上的 LaTeX 在沒有其他 package 的幫忙下必須使用絕對路徑，所以我後來提供了轉換，讓使用者可以依據圖片相對於目前 .docogen 的相對位置來做相對路徑的加入）
使用旗標 flag 來做選擇，可以讓你指定要絕對路徑還是相對，其值有: rel/abs 兩種
- flag 的預設值是 rel（如果留空的話就會是這個值）
  - 若 flag=abs, 我們則會直接使用 path 裏面的地址
  - 若 flag=rel, 我們則會依據目前使用到的這隻文檔的位置下去做相對轉絕對的路徑轉換
總共的項目有
- path：圖片路徑位置
- flag：上述提到的旗標
- align：圖片對齊功能（建議使用 center 即可）
- size：圖片大小（最佳排版大小:0.5~0.7 ）
- caption：圖片底下的說明文字
格式如下:

{
    name: "title image/figure",
    type: "figure",
    data: [
        {
            path: "absolute path of your image",
            flag: "abs/rel",
            align: "alignment method of your image",
            size: "size of your image",
            caption: "caption of image/figure"
        }, { ... }
    ]
}

web-restful-api

特化部份，為 restful api 格式的簡單支援
method: API 的 method
usage: API 的功能
url: API 的 URL 呼叫方式
description: 關於這部份 API 功能的詳細介紹
field: URL 使用到的參數
error: 當錯誤發生時，會出現的錯誤訊息
success: 當成功呼叫時，會出現的成功訊息

{
    name: "Restful api support",
    type: "web-restful-api",
    data: [
        {
            method: "GET/POST",
            usage: "usage of this url/function",
            url: "api url goes here(e.g. http://...)",
            description: "detail of this url/function",
            field: [ { name: "parameter field name", type: "parameter data type"}, ... ],
            error: [ "error msg 1", "error msg 2", ... ],
            success: [ "success msg 1", "success msg 2", ... ],
        }, { ... }
    ]
}

figure (outside)

和剛剛上面提過的 content 內部的格式相同，唯一不同的地方是這裡是跟 content 位在同一層；
內部的 figure 可以讓內文在講述時，可以有圖片穿雜；而外部圖片則是原本舊有的設計，選擇讓兩者同時並存，提高彈性

{
    ...
    figure: [
        {
            path: "absolute path of your image",
            flag: "abs/rel",
            align: "alignment method of your image",
            size: "size of your image",
            caption: "caption of image/figure"
        }, { ... }
    ]
}

subarticle

如果一篇文章還想繼續做進一步討論，則可以用 subarticle 繼續做延伸
這部份會依據現在的 article 的標號做延伸（比如：目前是 chapter 1, 則他的 subarticle 就是 1-1，以此類推）
為一個巢狀架構（目前的設計可以完美到 3 層的巢狀），可以在 subarticle 中再加入 subarticle 做繼續延伸！

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

JSON 腳本架構

架構概觀

主要部份

可延展部份

詳細功能介紹

title

priority

content

none

text

list

table

formula

code

figure

web-restful-api

figure (outside)

subarticle

English

繁體中文

Clone this wiki locally