Przygotowanie modułu Projektu SWORD: instrukcja

1. Wprowadzenie

Moduły Projektu SWORD są utworzone z dwóch elementów:

(1) plik z rozszerzeniem .conf, zawierającym informacje o lokalizacji modułu i jego atrybutach

(2) zbiór (najczęściej dwóch lub trzech) plików z treścią modułu - w formacie "rozumianym" przez program

Plik .conf jest umieszczony w katalogu mods.d programu SWORD. Plik ten winien być utworzony w jednym ze standardowych edytorów umożliwiających zapisanie niesformatowanego tekstu (notatnik - w j.polskim zapisz tekst  w formacie ANSI; emacs, vi, pico). Zawartość pliku jest opisana niżej (w części 2).

Pliki modułu są tworzone przez narzędziowe programy importujące z kilku formatów. Oznacza to, że musisz mieć przygotowany plik źródłowy (z tekstem, jaki chcesz mieć w formie modułu) - i ten plik przetworzyć do postaci modułu przy pomocy jednego z programów narzędziowych (dostępnych na naszych stronach).

Preferowanym formatem źródłowym (którego wsparcie jest rozwijane przez Towarzystwo CrossWire) jest format OSIS (obecnie tj. w lipcu 2004 nie dysponujemy narzędziami do importu w tym formacie dla środowiska windows). Import jest możliwy także z formatów ThML, GBF, niesformatowanego tekstu (w j.polskim najlepiej sprawdza się kodowanie polskich znaków w formacie UTF-8). Większość tekstów źródłowych wymaga przed utworzeniem modułu wpisania tagów (znaczników tekstowych) specyficznych dla przyjętego standardu (OSIS, ThML, GBF; opisy tych standardów znajdziesz w Sieci). Jest to zajęcie czasochłonne, do edycji warto zastosować język taki, jak np. Perl, jednak z pewnością konieczne będą korekty wprowadzane "ręcznie".

Po przygotowaniu dokumentu możesz utworzyć moduł i umieścić pliki wynikowe w odpowiednich lokalizacjach - wszystko omawiamy poniżej.

Potem, po sprawdzeniu modułu i upewnieniu się, że wszystko "działa", możesz dostarczyć swoją pracę zespołowi Projektu SWORD w celu udostępnienia jej ze stron Projektu.

2. Pliki z rozszerzeniem .conf

2.1. Przegląd pliku .conf

Plik .conf zawiera wszystkie informacje potrzebne do poprawnego odnalezienia i wyświetlania modułu. Każdy werset pliku składa się z nazwy funkcji i jej wartości. Oto przykład pliku .conf:

[Przykład]
DataPath=./modules/texts/ztext/przyklad/
ModDrv=zText
CompressType=ZIP
BlockType=Book
SourceType=GBF
CipherKey=1234ABCD5678EFGH
GlobalOptionFilter=GBFFootnotes
GlobalOptionFilter=GBFStrongs
GlobalOptionFilter=GBFHeadings
GlobalOptionFilter=GBFMorph
Feature=StrongsNumbers
Feature=DailyDevotion
Version=1.1
History_1.1=moduł zakodowany
Font=Ezra SIL
Category=Teksty próbne
Lang=he
Encoding=UTF-8
Description=Próbka przekładu
About=Ten plik .conf jest tylko próbką i\par {\i1 nie powinien} być wykorzystywany do innych celów
LCSH=Bible. English.
DistributionLicense=Public Domain
TextSource=CCEL

Przyjrzymy się teraz tej zawartości werset po wersecie:

Pierwszy werset  zawiera nazwę modułu w nawiasach kwadratowych (ta nazwa pojawi się w odpowiedniej zakładce programu).

DataPath to ścieżka do modułu, w odniesieniu do głównego katalogu programu. Wszystkie modułu są zwykle umieszczone w katalogu modules. Ma on cztery podkatalogi: texts, comments, lexdict oraz genbook. Katalog texts zawiera podkatalogi rawtext i ztext, które zawierają katalogi z wszystkimi zainstalowanymi modułami z tekstami Biblii. Katalog comments zawiera podkatalogi zcom, hrefcom, rawcom oraz rawfiles, w których znajdują się komentarze biblijne w czterech dostępnych formatach. Katalog lexdict zawiera podkatalogi zld, rawld i rawld4, dla tzrech obsługiwanych formatów słowników i czytań. Katalog genbook zawiera tylko jeden podkatalog rawgenbook. Nasz przykładowy moduł jest tekstem Biblii, stąd jego lokalizacja: ./modules/texts/ztext/przyklad/.

2.2. Atrybuty pliku .conf

ModDrv wskazuje, w jaki sposób pliki będą przetwarzane przez program narzedziowy; obecnie (lipiec 2004) jest dostępnych 10 trybów przetwarzania - należy wpisać tutaj jeden z nich: RawText, zText, RawCom, HREFCom, zCom, RawLD, RawLD4, zLD, RawGenBook, and RawFiles. Przykład trybów przetwarzania: Biblie RawText, słowniki RawLD4, codzienne rozważania RawLD.

CompressType wskazuje na rodzaj użytej kopmpresji; dotyczy to jedynie modułów utworzonych w trybie kompresji (zText, zCom, & zLD). Obecnie możliwe są 2 rodzaje kompresji: Zip (preferowany) oraz LZSS.

BlockType określa rozdrobnienie bloków tekstu dla skompresowanych modułów opartych na wersetach (zText & zCom). Możliwe wartości rozdrobnienia: Book, Chapter, oraz Verse (odpowiednio: księga, rozdział, werset).  Wg nas najlepiej określać rozdrobnienie dla modułów z Bibliami na poziomie Book, a dla Komentarzy jako Chapter, jednak należy to przetestować tworząc moduł. Im mniejsze rozdrobnienie, tym szybszy moduł, ale też tym większy...

BlockCount wskazuje na ilość tekstu "wtłoczoną" w pojedynczy blok skompresowanego modułu (moduły zLD). Możliwe wartości - dowolna liczba całkowita, domyślne ustawienie: 200. Wyższe wartości uczynią moduł mniejszym - ale wolniejszym.

SourceType może mieć wartość GBF, ThML, OSIS lub imp. Ten parametr wskazuje na format pliku źródłowego.

CipherKey to pole, w którym możesz umieścić klucz odblokowujący moduł zakodowany. Pozostaw pustą linię ("CipherKey=") dla wskazania, że moduł jest zakodowany, jeśli nie chcesz upubliczniać klucza. Pomiń ten atrybut dla modułów niekodowanych.

GlobalOptionFilter wskazuje na opcjonalne filtry dodatkowe, jakie mogą zostać użyte podczas wczytywania tekstu. Może być kilka linii podających wartości dla tego atrybutu. Dla tekstów w formacie OSIS: OSISStrongs oraz OSISMorph; dla tekstów w formacie ThML: ThMLFootnotes, ThMLStrongs, ThMLMorph, ThMLHeadings, ThMLVariants, THMLScripref, oraz ThMLLemma; dla tekstów w formacie GBF: The GBFFootnotes, GBFStrongs, GBFMorph, GBFHeadings, oraz GBFRedLetterWords. Teksty greckie mogą korzystać z filtra UTF8GreekAccents, a hebrajskie z filtrów UTF8HebrewPoints oraz UTF8Cantillation.

Feature wskazuje na pewne dodatkowe cechy tekstu i może przybierać wartości: StrongsNumbers (obecność numeracji Stronga ), DailyDevotion (moduły codziennych rozważań), GreekDef & HebrewDef (moduły z definicjami greckimi lub hebrajskimi, opisanymi liczbami Stronga), Glossary (glosariusze), GreekParse & HebrewParse (moduły z rozszerzeniami morfologicznymi w języku grecki lub hebrajskim).

Version czyli numer wersji modułu pozwala użytkownikom programu wiedzieć, czy używany przez nich moduł wymaga aktualizacji. Wersje zaczynamy określać od 1.0 i zwiększamy o 0.1 przy mniejszych zmianach a o większe wartości przy zmianach zasadniczych (np. po zmianie tekstu źródłowego).

History informuje o zmianach wprowadzanych w kolejnych wersjach modułu.

Font określa czcionkę modułu. Pomiń tą linię jeśli chcesz, żeby moduł był wyświetlany z użyciem domyślnej czcionki programu. Ostrożnie z określaniem tutaj i używaniem w pliku źródłowym modułu kodowań specyficznych dla czcionki lub grupy czcionek.

Category pozwala na umieszczenie modułu w odpowiedniej kategorii na stronie pobierania modułów. Atrybut kategorii służy do zaznaczenia modułu spoza chrześcijańskiej ortodoksji lub takiego, który wymaga wersji testowej oprogramowania. Pomiń ten atrybut jeśli twój moduł nie należy do jednej z tych kategorii.

Lang -  nie wgłębiając się w szczegóły radzimy pisać "pl" dla modułów w języku polskim.

Encoding określa kodowanie znaków w module. Preferowana wartość to UTF-8, jednak ustawieniem domyślnym jest Latin-1 (konieczne jest wpisanie tej linii w polskich modułach, najlepiej z wartością UTF-8).

Description to krótki (1 linia) opis modułu (np. tytuł).

About jest dłuższym opisem - tu może być informacja np. nt. copyrightu, źródeł itd. Informacja zawarta w tej linii może byc zapisana jako rtf lub jako goły tekst (bez formatowań).

TextSource to opis źródła tesktu - jako prose (such as "CCEL") lub adres URL.

LCSH określa miejsce w katalogu amerykańskiej Biblioteki Kongresu (Library of Congress Subject Heading). Możesz sprawdzić katalog tej Biblioteki http://catalog.loc.gov/ - dla znalezienia publikacji or z której robisz moduł lub dla określenia właściwego LCSH dla publikacji nieskatalogowanej.

DistributionLicense określa na jakich zasadach odbywa się dystrybucja modułu. Dopuszczalne wartości: "Public Domain", "Copyrighted", "Copyrighted; Permission to distribute granted to CrossWire", "Copyrighted; Free non-commercial distribution".

Copyright określa rok powstania ochrony prawem autorskim oraz właściciela tego prawa.

CopyrightContactName określa, kto jest dysponentem prawa autorskiego (= z kim się kontaktować).

CopyrightContactAddress określa adres pocztowy dysponeneta prawa autorskiego.

CopyrightContactEmail określa adres e-mailowy tegoż.

DistributionSource wskazuuje, gdzie można odnaleźć tekst (np. adres URL).

DistributionNotes to miejsce na wszelkie dodatkowe informacje na temat dystrybucji modułu.

SwordVersionDate określa datę utworzenia obecnej wersji modułu.

MinimumVersion wskazuje, jakaminimalna wersja programu jest konieczna dla odczytania modułu.

Obsoletes wskazuje na modułu, któreobecny moduł unieważnia (z reguły jest tu podana lista poprzednich nazw modułu)

3. Przygotowanie tekstu do importu

Wymagamy kodowania wszystkich dostarczanych tekstów jako Unicode (najlepiej UTF-8). Zalecamy oznaczanie tekstów znacznikami OSIS, jednak akceptujemy też znaczniki ThML lub GBF.

3.1. Kodowanie

Zmiana kodowania pliku źródłowego nie jest potrzebna dla modułów w języku angielskim, jeśli plik źródłowy jest utworzony wyłącznie ze znaków ASCII. W pozostałych przypadkach konieczna jest konwersja kodowania do UTF-8. Najłatwiej jest to zrobić przygotowując pliki źródłowe w edytorze umożliwiającym odpowiedni zapis (np. w środowisku windows - w notatniku -> zapis "plik tekstowy, kodowanie UTF-8").  Do konwersji tekstów w j.polskim wśrodowisku windows polecamy freeware'owy, bardzo profesjonalny  program Gżegżółka (http://www.gzegzolka.com/). Dwa inne polecane konwertery tekstów to uconv oraz font2uni:

uconv (część ICU)
dostępny w wersji skompilowanej dla Win32 (http://crosswire.org/ftpmirror/pub/sword/utils/win32/uconv.zip)
oraz jako źródła z ICU (http://oss.software.ibm.com/icu/).

font2uni z  CCEL (http://www.ccel.org/info/gkheb/)

Podczas tworzenia tekstów XML należy używać &amp; dla "&" i &lt; dla "<" (pozostałe oznaczenia są kodowane tak, jak ich odpowiedniki w UTF-8).

3.2. Oznaczanie tekstu

SWORD może przetwarzać trzy standardy tekstów biblijnych: OSIS, ThML, oraz GBFS, konwertując je na inne formaty (włącznie z RTF i HTML). Obecnie rozwijane jest jedynie wsparcie dla formatu OSIS (we współpracy z kilkoma towarzystwami biblijnymi). Informacje o w/w trzech standardach znajdziesz na stronach:

Open Scriptural Information Standard (OSIS) : http://www.bibletechnologies.net/
Theological Markup Format (ThML) : http://www.ccel.org/ThML/
General Bible Format (GBF) : http://www.ebible.org/bible/gbf.htm

Każdy plik źródłowy w formacie OSIS i ThML musi być prawidłowo opisanym, poprawnym plikiem XML-owym, z odpowiednio oznaczonymi wersami, hasłami słownika i rozdziałami tekstu. SWORD "widzi" tylko część tagów używanych w w/w standardach:

GBF: <WG>, <WH>, <WTG>, <WTH>, <RX>, <RF>, <FI>, <FB>, <FN>, <FR>, <FS>, <FU>, <FO>, <FV>, <CA>, <CL>, <CG>, <CM>, <CT>, <JR>, <JC>, <JL>, <TT>, & <TS> (plus odpowiednie tagi zamykające).

ThML: <sync> (z typicznymi parametrami liczb Stronga, morph, & lemma), <scripRef> i <note> (plus odpowiednie tagi zamykające). Możesz też użyć tagów XHTML-owych: <div>, <i>, <br>, oraz <b>.

Obecnie rozwijane jest możliwie pełne wsparcie dla standardu OSIS (docelowo - pełny zestaw tagów).

3.3. Format importu

3.3.1. Format OSIS oraz ThML - książki

Jeśeli dokument źródłowy jest poprawnym (walidacja!) plikiem XML zgodnym ze schematem OSIS lub z ThML DTD, nie będzie potrzebne dalsze jego przygotowanie - można go przetwarzać odpowiednim programem narzędziowym.  Narzędzia: xml2gbs oraz thml2gbs.

3.3.1. Format vpl

Format vpl (verse-per-line) może służyć wyłącznie do tworzenia modułów z Biblią. W tym formacie musisz umieścić na początku każdego wersetu oznaczenie zrozumiałe dla Sworda: "Genesis 1:1" lub "Jn 3:16". Wykaz nazw ksiąg i ich skrótów znajdziesz niżej (rozdz.7). Po tym oznaczeniu nastepuje w tej samej linii wers. Przykłady:

Genesis 1:1 Na początku stworzył Bóg niebo i ziemię.
Genesis 1:2 A ziemia była bezkształtna i pusta; ciemność zalegała nad powierzchnią otchłani. A Boży Duch unosił się nad powierzchnią wód.

Tak przygotowany plik źródłowy przetwarzasz przy pomocy narzędzia vpl2mod.

WAŻNE: obecna edycja programu wymaga konwersji wersyfkacji do układu Biblii Króla Jakuba. Różni się ona od powszechnie przyjętego w Polsce układu wersów - różnic jest kilkadziesiąt (wszystkie w obrębie Starego Testamentu). Wersyfikację oryginalną dla przetwarzanej Biblii możesz w formacie vpl zaznaczyć w nawiasach (format OSIS przewiduje specjalne oznakowania).

3.3.2. Format imp

Format imp lub import może być użyty do każdego rodzaju modułu (Biblie, komentarze, słowniki, codzienne rozważania, książki etc.).

Każde "wejście" (werset bibliny, hasło słownikowe, data itd.) w pliku imp może mieć dowolną ilość linii. Pierwszą linię "wejścia" należy oznaczyć znacznikiem "$$$<klucz>" - kluczem do wejścia będzie identyfikator wersetu, data, hasło słownika itd. Po pierwszej linii umieszczamy cały tekst "wejścia". Przykłady:

Biblie:

$$$Genesis 1:1
Na początku stworzył Bóg niebo i ziemię.
$$$Genesis 1:2
A ziemia była bezkształtna i pusta; ciemność zalegała nad powierzchnią otchłani. A Boży Duch unosił się nad powierzchnią wód.

Komentarze mają podobny format, jednak po każdym "wejściu" prawdopodnie będą nieco obszerniejsze. Możesz użyć zakres wersetów których dotyczy komentarz: np. "$$$Genesis 1:1-5", "$$$Exodus 1", "$$$Leviticus 1:1,5" itp.

Słowniki i leksykony powinny mieć taki wygląd:

$$$Adam
Adam był pierwszym człowiekiem stworzonym przez Boga.
$$$Ewa
Ewa była pierwszą kobietą stworzoną przez Boga.

Codzienne rozważania należy kodować wg klucza "$$$mm.dd", np. "$$$01.01" dla 1 stycznia albo "$$$12.31" dla 31 grudnia.

Książki: kodowany jest osobno każdy rozdział, w formie hiererchicznego drzewka (podobnego do struktury plików w katalogach). Na przykład, jeśli chcesz zakodować Dzieła Józefa, możesz nadać im taką strukturę:

$$$/Wojny
Wojny Żydów
$$$/Wojny/Księga 1
Pierwsza Księga Wojen Żydów
$$$/Wojny/Księga 1/Rozdział 1
Pierwszy rozdział Pierwszej Księgi Wojen Żydów
$$$/Wojny/Księga 1/Rozdział 1/Część 1
Część pierwsza pierwszego rozdziału Pierwszej Księgi Wojen Żydów
$$$/Wojny/Księga 1/Rozdział 1/Część 2
Część druga pierwszego rozdziału Pierwszej Księgi Wojen Żydów
Itd.

4. Import

Po przygotowaniu pliku do importu musisz użyć jednego z programów narzędziowych, zgodnie z opisem:

Jeśli twój tekst jest poprawnym dokumentem ThML, użyj thml2gbs.
Jeśli twój tekst jest poprawnym dokumentem OSIS, użyj xml2gbs.
Jeśli twój tekst jest Biblią w formacie vpl, użyj vpl2mod.
Jeśli twój tekst jest Biblią lub komentarzem w formacie imp, użyj imp2vs.
Jeśli twój tekst jest słownikiem, leksykonem lub codziennymi rozważaniami w formacie imp, użyj imp2ld.
Jeśli twój tekst jest książką w formacie imp, użyj imp2gbs.

W/w programy narzędziowe do importu plików znajdziesz jako źródła oraz skompilowane dla Win32 na stronie http://crosswire.org/ftpmirror/pub/sword/utils/win32/. Każde narzędzie ma krótki opis składni polecenia, widoczny po jegu uruchomieniu bez parametrów. Zapoznaj się uważnie z tym opisem (unikniesz błędów, np. tworząc moduł codziennych czytań musisz na końcu linii polecenia wpisać "2")!

W środowisku windows każdy z tych programów uruchamiasz z linii poleceń - musisz w tym celu umieścić w jednym katalogu (folderze) program narzędziowy i plik źródłowy. Np. tworząc moduł codziennych rozważań z pliku tekstowego dn.txt zapisanego jako imp (ze znacznikami $$$), wpiszesz "imp2ld dn.txt dn 2" (oczywiście bez cudzysłowów), tworzącmoduł o nazwie dn.

5. Dodatkowe narzędzia

Podczas tworzenia modułów Projektu SWORD możesz używać dodatkowych narzędzi, służących do kompresji modułów, ich blokowania przy pomocy klucza cyfrowego oraz sprawdzania brakujących wersów. Opis tych narzędzi znajdziesz na stronach w j.angielskim.

5.1. Kompresja modułów

Do kompresji Biblii, komentarzy lub modułów słowników i czytań służy program mod2zmod. Moduł musi być najpierw zainstalowany (widziany przez program Sword). Następnie uruchamiasz "mod2zmod <nazwa_modułu> <ścieżka_dostępu> [blockType [compressType]]". Parametr blockType może mieć wartości: 4 = księga (ustawienie domyślne), 3 = rozdział, lub 1 = werset - parametr ten określa  rozdrobnienie bloków tekstu poddawanego kompresji. Im większy blok, tym więcej czasu zajmie dotarcie do określonego miejsca w tekście, ale też skompresowany moduł będzie mniejszy. Parametr compressType może mieć wartość 1 = LZSS (ustawienie domyślne) lub 2 = Zip (to zalecamy).

Możesz wypróbować jak to działa w prakyce - my najczęściej używamy ustawień "rozdział" dla obszernych (tysiące stron) komentarzy, "księga" dla Biblii oraz algorytmu kompresji Zip.

5.2. Blokowanie modułów

Dla zablokowania modułu (Biblie - rawText lub komentarze - rawCom) służy narzedzie cipherraw. Uruchamiasz je z linii poleceń: "cipherraw </ścieżka/do/modułu> '<klucz>'". Klucz nie ma ograniczeń, w historii programu najczęściej używano klucza 16-znakowego.

5.3. Poszukiwanie brakujących wersetów

Znalezienie "pustych" wersetów ułatwia narzędzie emptyvss. Obecność takich wersetów w module jest niemal równoznaczna z błędami jego utworzenia. Uruchamiasz z linii poleceń "emptyvss <nazwa_modułu>" i otrzymujesz listę pustych wersetów.

6. Przesyłanie modułu / plików źródłowych do Projektu Sword

Zachęcamy do przesyłania nam utworzonych przez Ciebie modułów. Każdy moduł jaki chcesz upublicznić na naszej stronie musi zawierać plik źródłowy modułu i plik .conf.

Plik źródłowy winien być utworzony w formacie OSIS, ThML, imp lub vpl - tak, aby można było przetworzyć go przy pomocy odpowiedniego programu narzędziowego.

Minimalny zestaw informacji w pliku .conf, jakiego oczekujemy, zawiera pola: DataPath, ModDrv, Lang, Description, About, DistributionLicense, oraz TextSource.

Jeśli chcesz dostarczyć swój materiał, skontaktuj się z nami: sword@chrzescijanie.pl lub zadając pytanie bezpośrednio "zespołowi wsparcia" (w j.polskim) sword-pomoc@crosswire.org, podając nazwę modułu - ktoś odpowie ci, podając dalsze informacje.

7. Nazwy ksiąg Biblii (księgi protokanoniczne Starego Testamentu oraz Nowy Testament)*

* Księgi duterokanoniczne nie są obecnie obsługiwane przez program. Prawdopodobnie ich obsługa zostanie opracowana dla kolejnej edycji wersji dla windows.