CSV/Excel Workbook轉換建庫檔工具 -- 使用指南
歡迎使用DocuSky的建庫工具！
本系統讓使用者將整理過，含有文件內文與文件Metadata的檔案轉換成DocuSky建庫檔，以供使用者上傳。
目前支援的檔案格式有CSV(Comma Separated Values)格式的純文字檔以及Microft Excel檔案。
使用流程概述
  1. 建立文件資訊的資料表（輸入檔案與格式說明）
  2. 載入含有文件資訊的資料表
  3. 建立Metadata欄位/文件內文與資料表欄位的對應
  4. 輸出建庫檔
  5. 上傳至DocuSky建庫
建立文件資訊的資料表（輸入檔案與格式說明）
此工具接受兩種檔案格式，分別是CSV(Comma Separated Values)格式的純文字檔(副檔名為".txt"或".csv")，以及Microsoft Excel活頁簿檔案(副檔名為".xls"或".xlsx")。
（０）資料範例
點我下載範例檔案
後面對於輸入格式的說明中，會以此處的文件資訊內容示範如何建立能夠輸入工具的文件資訊檔案。
這個範例中，欲對兩組文獻集進行建庫，兩組文獻集都含有三個文件，以下是這些文件的資訊：
文獻集 檔名 標題 作者 文件來源 體裁/詞牌 內文
唐詩 TangPoetry_0001.txt 相思 王維 全唐詩 五言絕句 紅豆生南國，秋來發故枝。願君多採擷，此物最相思。
TangPoetry_0002.txt 黃鶴樓 崔顥 全唐詩 七言律詩 昔人已乘白雲去，此地空餘黃鶴樓。黃鶴一去不復返，白雲千載空悠悠。晴川歷歷漢陽樹，春草萋萋鸚鵡洲。日暮鄉關何處是，煙波江上使人愁。
TangPoetry_0003.txt 送友人 李白 全唐詩 五言律詩 青山橫北郭，白水繞東城。此地一為別，孤蓬萬里征。浮雲遊子意，落日故人情。揮手自茲去，蕭蕭班馬鳴。
宋詞 SongPoetry_0001.txt 秋日懷舊 范仲淹 全宋詞 御街行 紛紛墮葉飄香砌。夜寂靜、寒聲碎。真珠簾卷玉樓空，天淡銀河垂地。年年今夜，月花如練，長是人千里。愁腸已斷無由醉。酒未到、先成淚。殘燈明滅枕頭欹。諳盡孤眠滋味。都來此事，眉間心上，無計相回避。
SongPoetry_0002.txt 有美堂贈述古 蘇軾 全宋詞 虞美人 湖山信是東南美。一望彌千里。使君能得幾回來。便使尊前醉倒、且徘徊。沙河塘裏燈初上。水調誰家唱。夜闌風靜欲歸時。惟有一江明月、碧琉璃。
SongPoetry_0003.txt 梅 李清照 全宋詞 臨江仙 庭院深深深幾許，雲窗霧閣春遲。為誰憔悴損芳姿。夜來清夢好，應是發南枝。玉瘦檀輕無限恨，南樓羌管休吹。濃香吹盡有誰知。暖風遲日也，別到杏花肥。
（１）CSV(Comma Separated Values)格式說明
CSV是一種以文字符號呈現表格(table)格式的資料表示方法。在CSV中，每個分行代表一個橫列(row)的資料，橫列中的各項直欄(column)資料以逗號分隔。
以下是此工具對於輸入CSV檔案的規範與處理：
  1. 工具會視一個橫列中的資料為一項文件的資訊。
  2. 同一橫列中的直欄資料都要以半形雙引號 (") 含括起來，如原始資料內容若是 [cat] ，則在CSV檔中應寫作 ["cat"] 。如果資料內容當中含有半形雙引號，則需要將其改成「連續兩個半形雙引號」，以供程式辨識。如原始資料內容若是 [I said: "Hey!".] ，則CSV檔中應寫作 ["I said: ""Hey!""."] 。
  3. 若一項資料中含有換行字元，若有遵照前面的規則並不會影響程式辨識，或者也可以考慮用HTML格式中的換行標籤 (<br/>) 取代資料中的換行字元。
  4. 同一橫列中的直欄資料之間需以半形逗號 (,) 相隔。橫列中最後一項資料後面不必填寫逗號。如：["apple","orange","pear"]
  5. 若該欄當中沒有任何資料，可以不填寫任何內容，或是用連續兩個半形雙引號取代。如三個項目中，第二個項目沒有內容，則可以寫成：["apple",,"pear"]或是["apple","","pear"]
  6. 檔案中第一個橫列的資料會做為各項直欄的名稱(header)，有效的名稱應該含有空白、跳位(tab)與換行以外的字元，無效的名稱以及其對應的欄位資料會被略過。該列含有的直欄資料數量(不論資料內容是有效還是無效的名稱)會視為該表格的直欄數。
  7. 檔案第一行以後每行(也就是一個橫列)的直欄資料數量，必須和前述第一列的直欄數相等，不能超過或少於該數量。
  8. 檔案中的空行(不含任何字元的單行內容)在讀取時會被省略。
  9. 此工具主要支援UTF-8的編碼檔案，建議將檔案以UTF-8編碼儲存。
下面是由前面的範例資料建立的CSV檔案內容：((1)文件內文因篇幅只會列出部分內容，省略的部分以 (…) 顯示；(2)檔案中的換行點以 (↵) 符號顯示。)
Example_csv.csv
"文獻集","檔名","標題","作者","文件來源","體裁/詞牌","內文"↵
"唐詩","TangPoetry_0001.txt","相思","王維","全唐詩","五言絕句","紅豆生南…"↵
"唐詩","TangPoetry_0002.txt","黃鶴樓","崔顥","全唐詩","七言律詩","昔人已乘…"↵
"唐詩","TangPoetry_0003.txt","送友人","李白","全唐詩","五言律詩","青山橫北…"↵
"宋詞","SongPoetry_0001.txt","秋日懷舊","范仲淹","全宋詞","御街行","紛紛墮葉…"↵
"宋詞","SongPoetry_0002.txt","有美堂贈述古","蘇軾","全宋詞","虞美人","湖山信是…"↵
"宋詞","SongPoetry_0003.txt","梅","李清照","全宋詞","臨江仙","庭院深深…"
（２）Microsoft Excel檔案格式說明
Microsoft Excel是Microsoft公司發行的電子計算表格軟體。
若你使用的Excel版本為Excel 2003或以前的版本，建議使用「Excel活頁簿」(副檔名為".xls")格式儲存。
若是2007或以後的版本，建議使用「Excel 97-2003活頁簿」(副檔名為".xls")或「Excel活頁簿」(副檔名為".xlsx")這兩種檔案格式儲存。
以下是此工具對於輸入Excel檔案的格式規範：
  1. 工具會視一個橫列(row)中的資料為一項文件的資訊。
  2. 同一橫列中的直欄(column)資料會以欄位中顯示的值(value)為主。若在欄位當中使用函數(formula)，則會以計算後的值作為資料內容。
  3. 檔案中第一個橫列的資料 (A1, B1, C1, ...) 會作為各項直欄的名稱(header)。有效的名稱應該含有空白、跳位(tab)與換行以外的字元，無效的名稱以及其對應的欄位資料會被略過。
  4. 若檔案中含有合併儲存格(merged cells)，則儲存格範圍中的所有欄位資料都會是該合併儲存格的值。
  5. 基本上，讀取時會以最右側與最下方的非空資料欄位作為表格範圍。
  6. 在表格範圍中，若有不含任何內容的空列，在讀取時不會被省略。
  7. 此工具支援Excel檔案的分頁功能，您可以將不同組別的資料放在個別的資料表中分別載入。詳細後述。 (注意：若檔案中含有多個表格，沒有填寫資料的表格在輸入時不會被讀入。)
  8. 注意：Excel對於繁體中文資料的編碼預設為Big5，若你的原始資料含有Big5範圍以外的字元會造成亂碼問題，建議採用CSV格式檔案作為輸入。
下面是兩種由前面的範例資料建立的Excel檔案內容：(文件內文因篇幅只會列出部分內容，省略的部分以 (…) 顯示。)
1. 將所有資料放在同一份表格當中
Example_xls01.xlsx
Metadata--唐詩宋詞
◢ A B C D E F G
1 文獻集 檔名 標題 作者 文件來源 體裁/詞牌 內文
2 唐詩 TangPoetry_0001.txt 相思 王維 全唐詩 五言絕句 紅豆生南…
3 唐詩 TangPoetry_0002.txt 黃鶴樓 崔顥 全唐詩 七言律詩 昔人已乘…
4 唐詩 TangPoetry_0003.txt 送友人 李白 全唐詩 五言律詩 青山橫北…
5 宋詞 SongPoetry_0001.txt 秋日懷舊 范仲淹 全宋詞 御街行 紛紛墮葉…
6 宋詞 SongPoetry_0002.txt 有美堂贈述古 蘇軾 全宋詞 虞美人 湖山信是…
7 宋詞 SongPoetry_0003.txt 梅 李清照 全宋詞 臨江仙 庭院深深…
2. 將資料依文獻集分成兩份表格
Example_xls02.xlsx
唐詩
◢ A B C D E F
1 檔名 標題 作者 文件來源 體裁/詞牌 內文
2 TangPoetry_0001.txt 相思 王維 全唐詩 五言絕句 紅豆生南…
3 TangPoetry_0002.txt 黃鶴樓 崔顥 全唐詩 七言律詩 昔人已乘…
4 TangPoetry_0003.txt 送友人 李白 全唐詩 五言律詩 青山橫北…
宋詞
◢ A B C D E F
1 檔名 標題 作者 文件來源 體裁/詞牌 內文
2 SongPoetry_0001.txt 秋日懷舊 范仲淹 全宋詞 御街行 紛紛墮葉…
3 SongPoetry_0002.txt 有美堂贈述古 蘇軾 全宋詞 虞美人 湖山信是…
4 SongPoetry_0003.txt 梅 李清照 全宋詞 臨江仙 庭院深深…
（３）外部純文字檔案
此工具提供從資料表外部的純文字檔取得文件內文的資料。
如果您已經將文件內文以個別的純文字檔儲存，這個功能讓您不需要另行將內文編入資料表中。
  1. 資料表需要提供檔名的欄位，以供工具尋找對應檔按的檔名。
  2. 純文字檔需以UTF-8編碼格式儲存。
載入含有文件資訊的資料表
依照前面的方式編輯資料表後，您就可以開始使用這個工具。以下會用上述的資料內容作為範例，逐步講解如何整合資料表與建庫檔的資訊。
首先，在「步驟一：載入資料表格」這個區塊中載入您的資料表。
（１）CSV格式檔案
在「載入CSV或Microsoft Excel檔案」區塊中，在「檔案格式：」的部分點選「CSV」。
點選下方的「選擇檔案」，選擇您在本機端的資料表。
確定您要讀入的檔案後，點選下方的「讀入檔案」按鈕。工具會讀取您的CSV檔案，並自動將當中的表格欄位名稱帶入下個步驟的欄位。讀取完成後就可以進入下一步。
（２）Microsoft Excel檔案
在「載入CSV或Microsoft Excel檔案」區塊中，在「檔案格式：」的部分點選「Microsoft Excel」。
點選下方的「選擇檔案」，選擇您在本機端的資料表。
確定您要讀入的檔案後，點選下方的「讀入檔案」按鈕。
工具會搜尋檔案中含有欄位資料的分頁資料表，並顯示選擇分頁的下滑式選單。在下滑式選單點選要讀入的分頁。
點選選單右側的「讀入資料表」讀入表格內容。工具會自動將當中的表格欄位名稱帶入下個步驟的欄位。讀取完成後就可以進入下一步。
建立Metadata欄位/文件內文與資料表欄位的對應
讀取資料表後，會將資料表的欄位名稱帶入「步驟二：建立Metadata資料對應」部分的欄位中，在這個部分建立建庫檔與資料表之間的欄位資料對應。
（１）建立與建庫檔格式(ThdlExportXML)的標籤對應
在「建立與建庫檔格式(ThdlExportXML)的標籤對應」這個部分，會列出建庫檔格式中定義的文件Metadata資訊欄位名稱以及說明。您可以依照需求，指定這些欄位要填入輸入CSV/Excel資料表中哪一個欄位下的資料。
請從每個項目右側的下拉式選單選擇對應的資料表欄位名稱。如果您的資料不需要使用這個欄位，在對應的表格欄位選擇「無」即可。
需要特別注意的是目前格式中的兩個必填欄位：
1. corpus(文獻集名稱)
在一份資料庫中，所有文件會分類成數份文獻集。這個欄位會決定該文件屬於哪份文獻集，在該欄位有相同內容的文件會被歸類到同一份文獻集中，並以此欄作為文獻集名稱。
除了依照資料表中的欄位決定以外，您也可以選擇使用CSV檔的檔名，或是Excel檔中該資料表的分頁名稱做為文獻集名稱，這些檔案就會被歸類到同一份文獻集當中。要這樣做的話，請勾選"corpus"部分中「使用檔名(CSV)或資料表名稱(EXCEL)作為文獻集名稱」的選項。
以上述Excel檔案的兩種建立方式為例，如果使用的是第一種型式(Example_xls01.xls)，在下拉式設定對應的欄位「文獻集」，就會設定該欄位的資料作為corpus的內容。
如果使用的是第二種建立方式(Example_xls02.xls)，個別讀入「唐詩」或「宋詞」兩個資料表建立文獻集時，就可以選擇「使用檔名(CSV)或資料表名稱(EXCEL)作為文獻集名稱」帶入資料表名稱作為文獻集名稱。
2. filename(檔案名稱或編號(ID))
這個欄位的內容在文獻集中會作為編號(ID)，因此對於要歸類於同一份文獻集的文件，請確定此欄位不會有重複的值。如果選擇以外部純文字檔作為文件內文的來源，則工具會以此欄的內容對應檔案的檔名，取得檔案內容作為內文資料。
如果您的文件內容是直接列在資料表中，而且表格中並沒有給文件編列檔名或編號資訊，可以在"filename"部份選擇「自動生成ID」，工具會自動在此欄位建立不重複的編號。
以範例檔案「Example_xls01.xls」中的資料表「Metadata_唐詩宋詞」為例，在這個部份中建立的欄位對應關係如下圖：
（２）決定文件內文來源
此處決定文件內文的來源。一共有兩種來源：
1. 資料表中的欄位資料
您可以選擇以資料表中一項或多項欄位的資料作為文件的內文資料。
如果要從資料表取得內文，請勾選「從 CVS/Microsoft Excel資料表 的欄位取得內文資料」。下面會出現選擇對應欄位的下拉式選單，選擇要作為內文的欄位。
如果要整合資料表中多項欄位作為文件內文，請點選「新增內文對應欄位」按鈕，增加對應欄位的選項。生成文件資料時，會依上至下的次序將對應欄位的資訊接合成內文。
2. 外部檔案
如果你的文件內文是以個別的純文字檔儲存，請勾選「從外部檔案取得內文資料」。
點選「選擇檔案」後，從本機目錄選擇要載入的檔案（可以一次載入多個檔案）。確定檔案後點選右方的「讀入檔案」工具就會將純文字檔讀入。
「顯示外部文字檔列表」可以檢查你目前載入的所有檔案的檔名。如果你需要刪除檔案重新載入，請點選「刪除所有文字檔」，工具會將所有載入的純文字檔刪除。
注意：如果已經有將檔案載入工具，後來再載入的檔案名稱若與先前的檔案相同，則後來載入的檔案會取代原有檔案。
（３）建立其他Metadata
如果你有建庫檔規範以外的Metadata，這個部分可以讓你新增自定的Metadata。
點選「增加Metadata資訊」可以在下方新增一項自定的Metadata資訊。
在「Metadata名稱」填寫該Metadata的名稱，在「對應欄位」的下滑式選單中選取該Metadata要從資料表的哪個欄位取得資料。
以範例檔案為例，若要增加與「體裁/詞牌」這個欄位相關的Metadata，則可以在此處新增一項稱為「PoetryForm」的Metadata，並指定「體裁/詞牌」這個欄位作為資料內容。
注意：Metadata名稱至少要含一個字元。第一個字元必須是半形英文字母 (A-Z, a-z) 、半形底線 (_) 或半形引號 (:) 。其他字元則限定使用半形英文字母、半形阿拉伯數字 (0-9) 、半形底線、半形槓號 (-) 或半形句號 (.) 。
（４）建立文獻集
建立完文件各項資訊與資料表的對應之後，點選此步驟最下方的「建立文獻集」就可以依您提供的資訊建立文獻集。
如果使用的範例檔是「Example_csv.csv」或「Example_xls01.xls」，並且指定「corpus」的對應欄位為「文獻集」，則點選「建立文獻集」後會生成兩份文獻集，名稱分別為「唐詩」與「宋詞」。
如果使用的是「Example_xls02.xls」(沒有文獻集的欄位)，並使用分頁資料表名稱作為「corpus」的資訊，則會分別讀入當中的兩個分頁資料表，生成「唐詩」與「宋詞」兩份文獻集。
輸出建庫檔
在前面兩個步驟中，可以透過一份或數份資料表建立資料庫中的文獻集。文獻集建立完成後，就可以將這些文獻集輸出成一份建庫檔。
檢視已建立的文獻集
已建立的文獻集和文獻集內含的文件數量會表列於這個區塊。如果要刪除已建立的文獻集，可以點選項目右側的刪除按鈕。
輸出ThdlExportXml建庫檔
這邊可以將工具目前建立的所有文獻集統整成一份建庫檔。在「輸出檔案名稱」欄位為建庫檔命名後，點選「輸出檔案」即可將建庫檔儲存至本機端。
上傳建庫檔至DocuSky建庫
這個工具加載了DocuSky的資料庫管理工具，您可以在輸出建庫檔後，立即將檔案上傳至DocuSky建庫。
點選「點我開啟DocuSky資料庫管理工具」後，就會開啟DocuSky個人資料庫的管理介面。若您尚未登入DocuSky，工具會先要求輸入您的帳號與密碼登入DocuSky。
登入以後，點選「上載單份 ThdlExportXml 檔以建構文字資料庫」旁的「選擇檔案/Choose File」選擇本機端的建庫檔（一次只能選擇一個檔案），並在「文字庫名稱」欄位填寫資料庫名稱。再點選「開始上傳」即可將建庫檔上傳至DocuSky建庫。