# DocuXML 1.1 Scheme

<!-- 標籤 -->
###### tags: `DocuXml`, `文件狀態：停止更新`

<!-- 內文編輯更新資訊，若有更動此份文件內容，請更新此項資訊 -->
> [name=Sih-Pin Lai]
> [time=Mon, May 10, 2021 4:52 PM]

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

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

:::

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

## 基本架構

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

- 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 標籤風格。
- 一份 DocuXml的 XML，包含了兩個主要的區塊：
- 可有可無的文獻集詮釋資料 (Corpus Metadata)，以及文本的資料 (Documents)
## Corpus Metadata

<corpus name="CORPUS_NAME_1">
    <metadata_field_settings>
        <corpus>文獻集</corpus>
        <compilation>出處</compilation>
        <author>立契者</author>
        <!--更多使用者自訂後分類時metadata標籤顯示名稱...-->
    </metadata_field_settings>
    <feature_analysis>
        <tag name="Udef_TextTitle" type="contentTagging" default_category="Udef_TextTitle" default_sub_category="-"/>
        <!--更多使用者自訂Tag...-->
    </feature_analysis>
</corpus>
<corpus name="CORPUS_NAME_2">
    <metadata_field_settings>
        <!--更多使用者自訂後分類時metadata標籤顯示名稱...-->
    </metadata_field_settings>
    <feature_analysis>
        <!--使用者自訂Tag清單...-->
    </feature_analysis>
</corpus>
<!--更多Corpus...-->

:::warning
- 使用者可放入自己想放入的metadata資訊，但目前系統尚不支援Corpus Metadata，只支援使用者自訂標籤的後分類
:::
- 文獻集詮釋資料以標籤 `<corpus name="CORPUS_NAME">...</corpus>` 來包裝
- **\<feature_analysis\>**:
- 此標籤需含有屬於該corpus的documents內所有使用者自訂標籤，來使系統能夠做後分類，若使用者沒有紀錄，系統則不會幫使用者做後分類
- 標準使用者自訂Tag name必須開頭為**Udef_**
- 放入`<tag>`標籤之中，將name與default_category這兩個attributes設定成使用者自訂的標籤(Udef_XXX)
:::warning
- type與default_sub_category請分別設定成"contentTagging"與"-"，功能目前正在開發中...
:::
- 例：使用者自訂標籤"Udef_TextTitle"
- `<tag name="Udef_TextTitle" type="contentTagging" default_category="Udef_TextTitle" default_sub_category="-"/>`
- **\<metadata_field_settings\>**
- 在此 `<metadata_field_settings>` 的內容描述各項標籤在後分類時的顯示名稱，例如 `<author>立契者</author>`表示後分類時， 系統應該在後分類標題顯示「立契者」，而不是後分類代碼「AU」或 `<author>` 標籤的預設名稱「作者」。
:::warning
- 未來會將不同corpus的<Udef_XXX>標籤分開，目前<Udef_XXX>會用於整份XML檔內的documents
- 也就是將所有corpus合成一個`<corpus name="*">`，並將所有`<feature_analysis>`內的`<tag>`合成一份
:::

## Documents
- 其中，文獻集詮釋資料以標籤 `<corpus name="CORPUS_NAME">...</corpus>` 來包裝，文本資料則收納在 `<documents>...</documents>` 標籤之內。在 \<documents\> 標籤下，每篇文件以 `<document filename="UNIQUE_ID">...</document>` 的方式來存放。例如，若有三篇文件，\<documents\> 標籤的內容會長得像這樣：

<documents>
    <document number="1" filename="p0001">...</document>
    <document number="2" filename="p0002">...</document>
    <document number="3" filename="p0003">...</document>
</documents>

- 注意到，每一篇文件都**必須有 filename 屬性**，而這個 filename 屬性 應儲存唯一的文件辨識碼(UNIQUE_ID)。 若有多份文件有重覆的 filename 值，僅有一份文件會被儲存到 DocuSky 上。
:::warning
- 若使用者建立`<document>`時**沒有指定number屬性**，則DocuSky在對文件進行輸出時，會依照字典排序法（lexciographical ordering） 以文件辨識碼對文件進行排序。因此，若文件的辨識碼為 id1, id2, id10, id100， 排序後的結果將會是 id1, id10, id100, id2。為了避免這種狀況，通常我們需在辨識碼的流水號前補零：id001, id002, id010, id100，在排序後的順序依然是 id001, id002, id010, id100。
:::
- 人文研究者通常會利用「檔名」來對儲存在硬碟的文本進行編碼。 通常我們可以利用文本存放在硬碟的檔名，來作為文件的辨識碼。
## Document(單一文件)

<documents>
    <document number="1" filename="p0001">
        <corpus corpus_order="1">2018_new_本草經集注</corpus>
        <doc_content>
            <!--內文XML-->
        </doc_content>
        <!--DocuSky支援metadata Tags-->
        <xml_metadata>
            <!--DocuSky不支援metadata Tags-->
        </xml_metadata>
        <doc_user_tagging>
            <tag type="contentTagging" default_category="Udef_TextTitle" default_sub_category="-">Udef_TextTitle</tag>
        </doc_user_tagging>
    </document>
    <document number="2" filename="p0002">
        <!--文件metadata與內容...-->
    </document>
    <!--更多文件...-->
    <document number="1" filename="p0001">
        <corpus corpus_order="2">2017_new_本草經集注</corpus>
        <!--文件metadata與內容...-->
    </document>
    <!--更多文件...-->
</documents>

### 必填資訊
- **`corpus`： 文獻集名稱**
- number屬性：可指定文件屬於第幾個文獻集，若不填系統會案照corpus出現順序給定
- **`doc_content`: 內文XML**
- 內容可包含其他標籤
### Metadata標籤
- 其中，標籤 a or b 表示標籤 a 和標籤 b 是等價的，例如 `<author>王小明</author>` 和 `<author_name>王小明</author_name> `在建庫時會被視為相同的資料（若兩個標籤同時存在，DocuSky 僅會取其中一個值）。 如果一項標籤具有後分類代碼（例如 `<author>` 的代碼為 AU），表示 DocuSky 支援 對這個標籤進行後分類的處理。

#### Type 1: 文件來源資訊
- ##### 支援後分類
- `compilation` or `compilation_name`: 出處，後分類代碼"COMP"
- `author` or `author_name`: 作者，後分類代碼"AU"
- `topic`: 主題，後分類代碼"TP"
- `docclass`: 分類，後分類代碼"CLASS"
- `doctype`: 類型，後分類代碼"TYPE"
- `book_code`: 書碼，後分類代碼"BC"，可儲存自訂的文件分類編碼
- `doc_source`: 文本來源，後分類代碼"SRC"
- ##### 不支援後分類
- `compilation_order`: 出處的排序(整數)
- `compilation_vol`: 出處的第幾冊(整數)
- `title`: 標題
- `docclass_aux`: 子分類
- `doctype_aux`: 子類型
- `doc_subject`: 學科
- `doc_code`: 文件編碼
#### Type 2: 文件時間資訊
- ##### 支援後分類
- `time_dynasty`: 朝代，後分類代碼"DYN"
- `time_norm_kmark` or `era` or `time_era`: 帝號，後分類代碼"ERA"
- `time_varchar` or `time_ad_date`: 西元日期，後分類代碼"AD_YMD"
- `year_for_grouping` or `time_ad_year`: 西元年份，後分類代碼"ADY"
- ##### 不支援後分類
- `time_orig_str`: 原文時間字串
- `time_norm_year`: 中曆年份
- `timeseq_type`: 時間序列的類型
- `date_not_before` or `timeseq_not_before`: 時間序列「不在某時間點之前」(整數)
- `date_not_after` or `timeseq_not_after`: 時間序列「不在某時間點之後」(整數)
- `date_number` or `timeseq_number`: 時間序列「文件的時間點」(整數)
#### Type 3: 文件地理資訊
:::info
(DocuSky 會將地域的三個階層結合為 L1/L2/L3 形式)
:::
- `geo_aux` or `geo_level1`: 地域階層第一層，後分類代碼"GEO"
- `geo_extra` or `geo_level2`: 地域資訊第二層
- `geo` or `geo_level3`: 地域資訊第三層
- `geo_longitude`: 經度(浮點數)
- `geo_latitude`: 緯度(浮點數)
#### Type 4: 使用者自訂metadata標籤
:::info
包在\<xml_metadata\>...\<\/xml_metadata\>中
:::
- 例：

<xml_metadata>
  <SourceXml>PTT_TCL_93out_1516_merged_20161115.xml</SourceXml>
  <SN>e0112</SN>
  <Contributor>原件由國史館臺灣文獻館典藏，本數位作品由國立臺中圖書館及行政院文化建設委員會國家文化資料庫分別典藏</Contributor>
  <RelatedPerson>許汝旺(賣主);高亮錦(買主)</RelatedPerson>
  <LandNo>桃澗堡銅鑼圈庄九五七之五</LandNo>
  <OldDeedsClass>杜賣契</OldDeedsClass>
  <Price>拾元</Price>
  <Contractor>-</Contractor>
  <Date>道光十一年</Date>
</xml_metadata>

#### Type 5: 使用者自訂詞彙標記
:::info
包在\<doc_user_tagging\>...\<\/doc_user_tagging\>中
:::
- 此標籤需含有屬於該document內所有使用者自訂標籤，來使系統能夠做後分類，若使用者沒有紀錄，系統則不會幫使用者做後分類
- 標準使用者自訂Tag name必須開頭為**Udef_**
- 放入`<tag>`標籤之中，將name與default_category這兩個attributes設定成使用者自訂的標籤(Udef_XXX)
:::warning
- type與default_sub_category請分別設定成"contentTagging"與"-"，功能目前正在開發中...
:::
- 例：

<doc_user_tagging>
    <tag type="contentTagging" default_category="Udef_TextTitle" default_sub_category="-">Udef_TextTitle</tag>
</doc_user_tagging>

### 內文XML
- `<doc_content>` 允許以 XML 格式儲存標記後的內文 (tagged text)
- 建議 `<doc_content>` 的內容不但滿足 XML 格式， 也同時滿足 XHTML 格式。
- 在 HTML 中，標籤的名稱並沒有大小寫之分，例如 `<MyTag>`、`<MYTAG>` 和 `<mytag>`，就會被視為相同的標籤
:::info
包在\<doc_content\>...\<\/doc_content\>中
:::

<doc_content>
    ...
    <Udef_RelatedDrug>玉</Udef_RelatedDrug>，皆不得用已成器物，及塚中玉璞也。好玉出
    <LocName RefId="hvd_70749" Term="hvd_70749">藍田</LocName>
    ...
    <Udef_Harvesting>叩之鳴者，是真也</Udef_Harvesting>
    ...
    <PersonName>卞氏</PersonName>長號也。
</doc_content>

#### DocuSky支援標籤
**「標記分析」中預設會支援的標記**
- `<LocName>`: 標記地名
- `<PersonName>`: 標記人名
- `<SpecificTerm>`: 標記官名或其他特殊詞彙

**「標記分析」中預設會不支援的標記**
- `<Date>`: 標記時間
- 會被保留在文件中，但不會被「標記分析」所處理。

**使用者自訂標記 (user-defined tags)**
- 它們的標籤名稱必須以 **"Udef_"** 起頭（注意大小寫必須完全相同）
- 例如：`<Udef_RelatedDrug>`、`<Udef_Harvesting>`
- 如果希望 DocuSky 能對日期資料進行 標記分析，可以將 `<Date>道光拾壹年參月 日</Date>` 改為 `<Udef_Date>道光拾壹年參月 日</Udef_Date>`