# DocuXML 1.3 Scheme

<!-- 標籤 -->
###### tags: `DocuXml`, `文件狀態：維護中`

<!-- 內文編輯更新資訊，若有更動此份文件內容，請務必更新此項資訊 -->
> [name=Sih-Pin Lai]
> [time=Wed, Aug 11, 2021 9:55 AM]

<!-- 摘要 -->
:::success

<!-- 當前負責人使用高亮標示，新接替維護人員請加在第一個 -->
- **建立者**：賴思頻
- **維護者**：==賴思頻==

:::

<!-- 筆記正文開始 -->

## 一、基本架構

DocuXml 是 DocuSky 建構資料庫所使用的語言。它的目的是將欲建庫的所有文本資料包裝在 XML 檔案中，方便 DocuSky 從中擷取所需資訊來建立資料庫。所需的資料有：全文資料 (full-text)、詮釋資料 (metadata)、以及文本標記 (tagged text) 等資訊。建構好的資料庫，將可支援全文檢索、後分類 (post-classification) 與標記分析 (tag analysis)。

DocuXml有相當大的比例是繼承 THDL（臺灣歷史數位圖書館）所輸出的格式（稱為 ThdlExportXml）。有別於一般 coding 常用的 Camel style，在 ThdlExportXml 中的詮釋資料標籤多半採用 Underline style， 而內文的標記資訊則採用 Pascal style。未來我們將努力，改採一致的 Pascal style 標籤風格。另外，在自訂標籤時，需注意大小寫的問題。DocuSky 在系統呈現上使用 HTML，故字母相同但大小寫不同之標籤，雖在 XML 中可以被區分，但呈現上會視為相同，導致錯誤發生。

一份 DocuXml 的架構如下，包含了兩個主要的區塊：文獻集詮釋資料 (Corpus Metadata)，以及文本資料 (Documents)。

<?xml version="1.0"?>
<ThdlPrototypeExport>
<!--Corpus Metadata (optional)-->
<!--Documents (required)-->
</ThdlPrototypeExport>

## 二、文獻集詮釋資料 (Corpus Metadata)

在文獻集詮釋資料的區塊，設定上使用者可以放入任意自訂的詮釋資料，但目前系統尚不支援文獻集層級的詮釋資料功能，不過可以運用此區塊做文獻集中詮釋資料與標籤在 DocuSky 上的後分類設定。

文獻集詮釋資料的編寫格式如下，於 `<corpus>` 標籤內填寫文獻集名稱（若詮釋資料為多個文獻集共用，填入 *），並使用 `<feature_analysis>` 、 `<metadata_field_settings>` 與 `<PageParameters>` 分別設定系統預設詮釋資料欄位、自訂標籤的後分類、以及其顯示的數目。

<corpus name="corpus_name">
<!-- Post-Classification of Metadata -->
<metadata_field_settings></metadata_field_settings>
<!-- Post-Classification of MetaTags -->
<feature_analysis></feature_analysis>
</corpus>

### 2.1 <metadata_field_settings>

此標籤用於紀錄該文獻集中，系統預設詮釋資料欄位的後分類設定。未記錄視為欲將該詮釋資料欄位的後分類隱藏，若要開啟後分類，需以下列格式紀錄於此標籤中：使用欄位名稱的標籤包裝其後分類顯示名稱，並以屬性 `show_spotlight="Y"` 設定開啟後分類、以屬性 `display_order` 設定後分類的顯示順序 (1-999，999 為系統預設順序)。若未做這部分的設定，系統會自動開啟後分類，並顯示系統預設的後分類名稱或者後分類代碼。

<metadata_name show_spotlight="Y" display_order="999">post-
  classification name</metadata_name>

### 2.2 <feature_analysis>

該文獻集中的標籤若需要後分類功能，可於此標籤處紀錄。一筆紀錄的格式如下，需有 `<spotlight>` 與 `<tag>` 兩種設定，在屬性值內填入的標籤名稱必須以 `Udef_` 開頭，一樣使用屬性 `display_order` 設定後分類的顯示順序，須為從 1 開始的連續整數，並用 `title` 屬性設定顯示的後分類名稱。

<spotlight category="Udef_tag_name" sub_category="-" display_order="1"
  title="post_classification_name"/>
<tag type="contentTagging" name="Udef_tag_name"
default_category="Udef_tag_name" default_sub_category="-"/>

於此之前，標籤設定使用的是 `<doc_user_tagging>`，分散於各個 document 的資料中，現已將此設定整併，將不再支援 `<doc_user_tagging>`。

### 2.3 \<PageParameters>
DocuSky 可針對某項後分類調整其回傳的最大數量，但仍有數量上限（為了效能考量，目前上限是 2000；超過這數量，建議利用 metadata/tags 分階層）。設定的方式是在 DocuXml 最前方的` <corpus> `設定標籤內，加上`<PageParameters>`的參數設定。

以下方程式碼為例，預設後分類回傳最多 200 項，但對於 metadata (PC) 後分類 ADY，則調整為最多 1200 項。

<PageParameters>
    <MaxCueItems Default="200">
        <Spotlight Name="PC:ADY">1200</Spotlight>
    </MaxCueItems>
</PageParameters>

備註：metadata 後分類是 PC，tag 及 metatags 則是 TA。

* 若需要在檢索頁啟用 分類樹(CatTree) 功能，需在 `<PageParameters>` 標籤下新增 `<CorpusTrees>`這個標籤。分類樹功能可以應用在後分類的 metadata 或 metatags 欄位上，可以同時展示多個欄位的分類樹，對於每棵分類樹需在 `<CorpusTrees>`下加入標籤`<CorpusTrees>`。

以下用 metadata欄位"CAT" 及 metatags欄位"Udef_hakkaevent"作為例子：

<PageParameters>
    <CorpusTrees>
        <CatTree Title="metadata_tree" Spotlight="PC:CAT" LeafDisplayFormat="%cue% (共 %cnt% 件, 共 %groups% 案)" InternalDisplayFormat="%cue% (共 %cnt% 件, 共 %groups% 案)" HideTextBeforeSymbol=""/>
        <CatTree Title="metatags_tree" Spotlight="TA:Udef_hakkaevent/-" LeafDisplayFormat="%cue% (共 %cnt% 件, 共 %groups% 案)" InternalDisplayFormat="%cue% (共 %cnt% 件, 共 %groups% 案)" HideTextBeforeSymbol="" OneToOne="false"/>
    </CorpusTrees>
</PageParameters>

`<CatTree>`標籤的各屬性說明如下：
* `Title`：樹名。
* `Spotlight`：欲分類的後分類欄位名。
1. 若後分類屬於metadata欄位，格式為 "PC:(後分類代碼)"。後分類代碼可以參考 表（一） 的後分類代碼欄。如 "PC:CAT" 為用
`<doc_category_l1><doc_category_l2><doc_category_l3>`組成三層的分類樹。
3. 若後分類屬於metatags欄位，格式為 `TA:(category)/(sub_category)"`。category與sub_category分別是欲分類的metatags後分類的spotlight標籤中， `default_category`與 `default_sub_category` 的特性值。例如 "TA:Udef_hakkaevent/-" 為用
`<spotlight default_category="Udef_HakkaIdentity" default_sub_category="-"/>`這個欄位分類。
* `LeafDisplayFormat`：葉節點的量詞格式，分類樹的每個節點都會有一段文字，顯示後分類名及文件數量。
例如 `"%cue% (共 %cnt% 件,共 %groups% 個)" `。 $cue% 會自動被替換成後分類的類別名； %cnt% 會被替換成類別的件數； %groups% 會被替換成計算所屬文件的<book_code>欄位值的不同數量。
* `InternalDisplayFormat`：內部節點的量詞格式。 如同葉節點的量詞格式寫法。
* `HideTextBeforeSymbol`：在節點的文字中，隱藏某字元前的所有字。預設為""。
* `OneToOne`：文件與類別的關係是否為一一對應，若是則填入"true"；若否(如應用多值欄位時，一份文件同時屬於多個類別)，則填入"false"。

`<HideCueDisplayBeforeSymbol>`、`<CueSeparator>` 標籤的說明如下：

在側邊欄的各項項目中，隱藏該字元之前的前綴。如此一來，即可透過特殊的前綴設定完成自訂的項目排序（例如依朝代排序），而不會影響檢索頁畫面的呈現。

與其相配合，有一標籤「項目分隔符 `<CueSeparator>`」可供設定（預設為 `;`）。若存在多個後分類項目同時具有前綴，即可將其分隔出來，並個別隱藏其前綴。例如可將某詮釋資料後分類項目「07_03=東晉;07_02=前秦」在依照朝代順序排列的同時，以「東晉;前秦」呈現。

<PageParameters>
  <HideCueDisplayBeforeSymbol>=</HideCueDisplayBeforeSymbol> 
  <CueSeparator>;</CueSeparator>
</PageParameters>

## 三、文本資料 (Documents)

文本資料收納在 `<documents>` 的標籤內，並以 `<document>` 標籤分別存放每篇文件的各式資料，其格式如下：

<documents>
<document filename="p0001">...</document>
<document filename="p0002">...</document>
<document filename="p0003">...</document>
</documents>

每篇文件都必須有 `filename` 的屬性來儲存建庫檔 (XML) 中唯一的文件辨識碼 (UNIQUE_ID)。人文研究者通常會利用「檔名」來對存放在硬碟的文本進行編碼，我們可以利用此檔名來作為文件的辨識碼。另外，DocuSky 會將 `filename` 依照字典排序法 (lexicographical ordering) 來對文件進行排序。因此，若 `filename` 為 id1、id2、id10、id100，排序後將會是 id1 > id10 > id100 > id2。為了避免這種狀況，需在 `filename` 中的流水號前補零：id001、id002、id010、id100，排序才會正確。

### 3.1 單一文件 (document)

一份文件的資料包括詮釋資料與內文，其中詮釋資料又分為系統預設欄位與使用者自訂的欄位，而內文中除了允許標記的文本內容外，亦可替文件添加多值標籤 (MetaTags，預設 不可檢索 NoIndex="1" ；可檢索 NoIndex="0")。其架構與格式如下所述：

<document filename="p0001">
<!-- System Defined Metadata -->
<metadata_name>metadata_value</metadata_name>
...
<!-- User Defined Metadata -->
<xml_metadata>
<metadata_name>metadata_value</metadata_name>
...
</xml_metadata>
<!-- Document Content -->
<doc_content>
<!-- Text (with Tags) -->
...
<!-- MetaTags -->
<MetaTags NoIndex="1">
<metatags_name>metatags_value</metatags_name>
...
</MetaTags>
</doc_content>
</document>

### 3.2 系統預設詮釋資料欄位 (Metadata)

DocuSky 預設的詮釋資料欄位皆記錄於規範表[^MA]中，使用前建議先詳閱各個欄位說明與格式規範，以選擇最適合的欄位對應。當中必須填寫、不可忽略的詮釋資料為 corpus 與 filename，其他詮釋資料則依照各自需求填寫。

[^MA]: [詮釋資料預設欄位規範表](https://docs.google.com/spreadsheets/d/1G7UPZv-G1D7Yowwj_r7pO7rZXmr16PrxEZQ22_bqFIw/edit?usp=sharing)

filename 的填寫是在 `<document>` 標籤上，並非為獨立的詮釋資料標籤，corpus 與其他詮釋資料的填寫則需以詮釋資料名稱為標籤名，包裝詮釋資料之值，範例如下。當中 corpus 可以帶有屬性 `corpus_order` 來指定文獻集的順序，若未指定則會依照 XML 中出現的順序給定。在填寫過程中，需注意詮釋資料標籤內的內容，請避免輸入標點符號、空白、或其他特殊符號，以免出現不可預期之錯誤。

<corpus corpus_order="1">corpus_name</corpus>
<title>title_string</title>
<author>author_name</author>

系統預設的詮釋資料欄位有三個類別：文件資訊、地理資訊、和時間資訊，每個類別都各自有支援後分類處理的欄位，簡單表列如下：

#### 表（一）：文件資訊欄位

#### 表（二）：地理資訊欄位

#### 表（三）：時間資訊欄位

### 3.3 使用者自訂詮釋資料欄位 (xml_metadata)

若系統預設的欄位中找不到適合的欄位對應，或者想讓詮釋資料顯示在系統中，需在 `<xml_metadata>` 標籤下填寫自訂欄位。填寫方式與預設欄位相同，以詮釋資料名稱為標籤名，包裝詮釋資料之值，唯需自行取詮釋資料名稱。另外，自訂欄位可以為資料添加超連結，在資料外包上一層超連結標籤 `<a>` 並附上連結即可。

<xml_metadata>
<!-- without Link -->
<metadata_name>metadata_value</metadata_name>
...
<!-- with Link -->
<metadata_name><a href="link" target="_blank">metadata_value</a>
</metadata_name>
...
</xml_metadata>

### 3.4 文件內文 (doc_content)

在 `<doc_content>` 內可以存放標記過後的文字 (tagged text)，但標記編寫需滿足 XML 格式，建議也同時滿足 XHTML 格式。DocuSky 支援的標記具有多種不同的功能，包括標記分析與後分類、標示文本結構層次、對讀、註記與註解等，以下將一一介紹。

DocuSky 支援內文標記的分析功能，系統預設可做後分類的標記有四個：`<PersonName>` 為人名、`<LocName>` 為地名、`<Date>` 為日期、`<Office>` 為職官，若有其他標記需求，也可以使用帶有 `Udef_` 前綴的自訂標記，將欲標記的文字以上述標籤包裝即可。以下提供一段經過標記的文本，在過程中可以透過各種屬性的添加[^CT]來豐富資料庫的功能：

[^CT]: [標記規範表](https://drive.google.com/file/d/1zybh-VBREtLJgujQhMmRCI23o7VuTrtn/view?usp=sharing)

* `Term`：填入欲參照的權威詞，在後分類中將會視為同一個詞進行統計。
* `RefId`：只支援人名與地名，可以填入欲參照的規範編碼，像是來自 CBDB 的人名 (cbdb_id)、TGAZ 的地名 (hvd_id)、TWGIS 的地名 (twgis_id)、法鼓規範資料庫 (dila_id) 的人名、地名等等，也可以直接放入連結網址或者經緯度座標（格式：xy=經度,緯度），系統將會連結標記與參照資料庫的資料。
* `Aux`：填入游標停留時顯示的文字。
* `Url`：填入欲參考的資源網址，資料庫將顯示連結的圖示。

...
永寧寺，<Date Aux="公元516年:北魏孝明帝">熙平元年</Date><PersonName
  Term="胡氏" RefId="A002046" Url="https://zh.wikipedia.org/wiki/xxx">靈
  太后胡氏</PersonName>所立也，在宮前閶闔門南一里御道西。
〈其寺東有<Office Term="太尉">太尉</Office>府，西對永康里，南界昭玄曹，北
  鄰<Office Term="御史">御史</Office>臺。
...
去<LocName Term="京師" RefId="hvd_82837">京師</LocName>百里，已遙見之。
...
<Udef_Construct Term="刹">刹</Udef_Construct>上有金<Udef_Construct
  Term="寶瓶">寶瓶</Udef_Construct>，容二十五斛。
...

若想為整份文件標上多值的標記，可以在內文後面添加 `<MetaTags>` 標籤，其格式與範例如下，每個自訂標記可以有多個值。多值標記的後分類統計亦會呈現在標記分析之中，預設上每個標記統計以 1 計算，若想設定該標記的計算次數，可以使用屬性 `Frequency` 填寫。

<MetaTags NoIndex="1">
<Udef_element>女巫</Udef_element>
<Udef_element>巫術</Udef_element>
<Udef_element>蘋果</Udef_element>
<Udef_element>王室婚禮</Udef_element>
<Udef_charactor Frequency="1">公主</Udef_charactor>
<Udef_charactor Frequency="1">王子</Udef_charactor>
<Udef_charactor Frequency="7">矮人</Udef_charactor>
</MetaTags>

除了上述標記，DocuSky也支援對話標記，並能根據對話標記，顯示文件的對話關聯圖。將欲標記對話用`<TagSpeak>`標籤包住，裡面再加上`<SpeakForm>`、`<SpeakTo>`、`<SpeakType>`三個標籤，其完整格式如下所示。
其中`<TagSpeak>`屬性：
* TagId：每個標籤的唯一識別碼
* Position：此對話在文章中的位置
* Continue：為前n句話的接續
* ContinueAbs：接續的話的TagId
* FinishTagging：是否為完整標記(有標了說話者、聆聽者和對話類型)

`<SpeakFrom>`和`<SpeakTo>`中的屬性：
* Name：此角色的名字
* Type：此角色是否為重要角色(0為重要，1為不重要)
* TagId：此角色的唯一識別碼

`<SpeakType>`中的屬性：
* Name：此對話類型的名稱
* Value：此種對話類型的識別碼

雲大呼曰：「<TagSpeak TagId="conversation0" Position="198" Continue="0" ContinueAbs="conversation0" FinishTagging="true">翼德援我！
<SpeakFrom Name="趙雲" Type="0" TagId="0"/>
<SpeakTo Name="張飛" Type="0" TagId="1"/>
<SpeakType Name="請求" Value="12"/></TagSpeak>」

在 DocuXML 文件中，可以對內文分段，為文本結構做層次。在 `<doc_content>` 的下一層允許使用 `<Paragraph>` 將整個段落包裝起來，並可以指定 `Key` 與 `Type` 屬性，系統會將其以 Key:Type 的形式加註顯示在段落開頭，屬性 `Title` 則可以設定游標停留時顯示的文字。

<Paragraph Key="001" Type="chap1" Title="序章">段落內文</Paragraph>

針對對讀需求的文本，提供 Align 標籤進行錨點的標記並搭配文本對讀工具做使用，其組成包含標示錨點開頭位置的 `<AlignBegin>` 與標示錨點結尾位置的 `<AlignEnd>`，其格式如下，具有四個屬性值供設定：

* `Key`：必填，用於 `<AlignBegin>` 與 `<AlignEnd>` 的配對，需是一份文件中唯一的識別碼。
* `Type`：必填，對讀標記的名稱。
* `RefId`：選填，識別對應關係使用，欲對照的段落需填入相同 ID。
* `Term`：選填，段落的簡短描述、標籤。

<AlignBegin Key="xxx" Type="yyy" RefId="zzz" Term="uuu"/>
...欲對讀的段落內文...
<AlignEnd Key="xxx"/>

DocuSky 也支援對文本內容進行註解與註記，只是目前尚在實驗階段，只提供顯示的功能。註解為對整個段落的文字評論，使用額外的 `<Comment>` 標記，每條評論使用 `<CommentItem>` 包裝，格式與 `<MetaTags>` 類似。可以附加 `Level`、`Category` 的屬性來標明註解的對象與分類，但目前尚無作用。

<Comment Level="Paragraph">
<CommentItem Category="傳">...</CommentItem>
<CommentItem Category="箋">...</CommentItem>
</Comment>

註記類的標籤用來標記文本內加註的文字，目前有四種，皆可以添加 `Type` 屬性，目前只做顯示用：

* `<Annotation>`：註釋，可以是同義字標示、準確用字、確切指稱對象等等，顯示為 a:Type。
* `<Quotation>`：引言，人物說話的內容、於現代文章中會被引號框起來的文字內容，顯示為 q:Type。
* `<Proofreading>`：校對，後人閱讀文獻時紀錄的校對資訊，顯示為 pr:Type。
* `<Postscript>`：後記，後人閱讀文獻時留下的簡短註記，顯示為 ps:Type。

李<Annotation Type="원주">【太祖舊諱】</Annotation>萬戶
作詩致賀曰: <Quotation Type="-">...</Quotation>
<Proofreading Type="광해군일기중정초본_차이">答</Proofreading>曰:
<Postscript Type="史論">【史臣曰:...】</Postscript>

### 3.5 分類樹 (CatTree).....
分類樹可以應用在metadata或metatags二種欄位。
對於系統預設具階層的後分類，如後分類代碼CAT會分類<doc_category_l[1|2|3]>，可以參考 **2.3 \<PageParameters>** 的說明新增<CatTree>標籤，不需要修改<doc_content>內文。
分類樹可以幫有多個具階層結構的metatags欄位做成樹狀結構圖，如某文件的某metatags欄位值為 `a/b/c;d/e` ，表示這份文件同時屬於a/b/c的三層結類別與d/c的二層結構類別。同樣可以參考 **2.3 \<PageParameters>** 的說明新增<CatTree>標籤，也不需要修改<doc_content>內文。

如果使用者欲自訂metadata欄位組合成新的分類樹結構，如 `doc_type/doc_class/geo_level1` ，而非系統預設的後分類階層，則須將這些欄位的值合併成單一metatags的值，如<doc_type>值為a，<doc_class>值b，<geo_level1>值c，需新增一個metatags欄位，值為a/b/c，最後替這個metatags欄位設定分類樹。建庫檔管理工具或分類樹工具可以自動完成這一段步驟。

### 3.6 關聯圖 (Event).....

## 四、DocuXML欄位與 Json 欄位對照

DocuSky 的工具可以透過 API 與 Widget 來存取雲端資料庫，從伺服器返回的資料格式為 Json，文本資訊存在 `docuList` 中的 `docInfo` 裡，包含本標準所述之資料與建庫時自動產生之資料。以下將列表描述本標準的欄位與 Json 的欄位之對應關係。

#### 表（四）：欄位對照表