Difference between revisions of "OSIS Genbooks"

From CrossWire Bible Society
Jump to: navigation, search
m (Change osisRefWork="book" to osisRefWork="GenBook")
 
(44 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
=Introduction=
 +
Much of what follows applies to any OSIS file, but there are a few features unique to genbooks (mainly in structure). This document aims to provide a complete, though not exhaustive, account of how to encode an OSIS genbook to become a SWORD module.
 +
 +
Keep in mind that, as with any XML document, elements are arranged hierarchically. The root node ends with the </osis> element, so the rest of the document occurs within that container. Within that is the Work node. Within that is the Header and then the Body of the text, which are parallel to each other. For a complete OSIS XML file, see Example OSIS Genbook below.
 +
 +
=Root Node=
 +
The root node for a Genbook is the same as any other OSIS document.
 +
 +
<pre><?xml version="1.0" encoding="UTF-8"?>
 +
 +
<osis xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace
 +
      http://www.bibletechnologies.net/osisCore.2.1.1.xsd"
 +
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 +
      xmlns="http://www.bibletechnologies.net/2003/OSIS/namespace">
 +
 +
 +
</osis>
 +
</pre>
 +
 +
=Work Container=
 +
 +
The Work container for a Genbook is the same as any other OSIS document except the reference system (osisRefWork) is simply "GenBook".
 +
 +
<pre>
 +
<osisText osisRefWork="GenBook" xml:lang="en" osisIDWork="WorkID">
 +
 +
</osisText>
 +
</pre>
 +
 
=Header=
 
=Header=
−
==Namespaces==
+
The Header should contain work elements for the current work and any other works to which this document links. In this example, the Bible is linked through Scripture references, and the KJV default reference scheme is used. More detailed information can be added, but the following is sufficient for a simple book with one author.
−
==Header Proper==
+
 
 +
<pre>
 +
<header>
 +
 
 +
<work osisWork="WorkID">
 +
<title>OSISGenbook</title>
 +
<creator role="aut">Author's Name</creator>
 +
</work>
 +
 
 +
<work osisWork="Bible">
 +
<refSystem>Bible</refSystem>
 +
</work>
 +
 
 +
</header>
 +
</pre>
 +
 
 
=Body=
 
=Body=
−
==Books and Book Groups==
+
==Basic Structure==
−
==Major Sections==
+
A <body> element is not used in OSIS. Instead, the body consists of <nowiki><div></nowiki> elements in a hierarchical structure. If you are encoding a collection of works by the same author, you can use the element <nowiki><div type="bookGroup"></nowiki> for the outer container. Otherwise start with <nowiki><div type="book"></nowiki>. The following represents several levels of containers.
−
==Chapters==
+
 
−
==Sections and Subsections==
+
<pre>
 +
<div type="book" osisID="Book">
 +
  <div type="majorSection" osisID="majorSection 1">
 +
      <div type="chapter" osisID="Chapter 1">
 +
        <div type="section">
 +
            <div type="subSection">
 +
            </div>
 +
        </div>
 +
      </div>
 +
  </div>
 +
</div>
 +
</pre>
 +
 
 +
Of course you decide what is in the osisID (within the bounds of what the schema allows--basically you should stick to letters, numbers, and spaces), and the <title> element can be used to create titles for each chapter, etc. You may define your hierarchy to as much detail as you like. However, remember that readers of SWORD genbooks can only read one container at a time, so if you define lots of subsections it forces the reader to flip through them. If those parts are short, consider just adding section titles and limiting your containers to chapters for ease of reading.
 +
 
 
==Basic Formatting==
 
==Basic Formatting==
 +
===Titles===
 +
Titles are defined using the <title> element:
 +
<pre><title>Title Name</title></pre>
 +
===Paragraphs===
 +
Paragraphs are defined using the <nowiki><p></nowiki> element.
 +
<pre><p>Your paragraph goes here.</p></pre>
 +
===Italic Text===
 +
For italics, use the <nowiki><hi type="italic"></nowiki> element.
 +
<pre><hi type="italic">Italic text</hi></pre>
 +
===Bold Text===
 +
To make text display in bold type, use the <nowiki><hi type="bold"></nowiki> element.
 +
<pre><hi type="bold">Bold text</hi></pre>
 +
===Superscript and Subscript===
 +
To make text superscript and subscript, just use the <nowiki><hi></nowiki> element with the type defined as "super" for superscript text and "sub" for subscript text.
 +
<pre><hi type="super">Superscript text</hi>
 +
 +
<hi type="sub">Subscript text</hi></pre>
 +
 
==Footnotes and Endnotes==
 
==Footnotes and Endnotes==
−
==Scripture References and other Links==
+
Footnotes and endnotes are encoded in the same way except for their type name. Both use the <nowiki><note></nowiki> element. Using the "n" attribute you can define the number, letter, or symbol which you want to appear for the note, but not all front-ends will display that.
 +
<pre><note type="x-footnote" n="1">Footnote text</note>
 +
 
 +
<note type="x-endnote" n="i">Endnote text</note></pre>
 +
 
 +
==Scripture References and Other Links==
 +
===Scripture References===
 +
Scripture references may be encoded as links which some front-ends will use to open that reference in a Bible window. This is done using the <nowiki><reference></nowiki> element with the attribute "osisRef" defining the target verse or passage. Note the variety of possibilities for these kinds of references below.
 +
<pre>
 +
<reference osisRef="Gen.1.1">Genesis 1:1</reference>
 +
<reference osisRef="Ps.119">Psalm 119</reference>
 +
<reference osisRef="Prov.1-Prov.9">Proverbs 1-9</reference>
 +
<reference osisRef="2Cor.6.14-2Cor.7.1">
 +
</pre>
 +
Bible book names are those abbreviations found in the OSIS manual (they basically follow the SBL abbreviations), and each portion of the reference is separated by a period. In a range of verses the book and chapter must be repeated and separated by a dash.
 +
===Internal Links===
 +
Links from an OSIS module to a non-verse-keyed OSIS module should use an '''osisRef''' of the format<ref>Currently this syntax works but does not validate to '''osisCore.2.1.1.xsd'''</ref>:
 +
 
 +
Module:Div1/Div2/Div3
 +
 
 +
Hence, if the module '''EarlyFathers''' were OSIS<ref>It's actually ThML. Install from the Xiphos repository.</ref>, the introduction page may look like:
 +
 
 +
<pre>
 +
<div type="section" osisID="Introduction">
 +
<title>The Early Church Fathers Series</title>
 +
<p>
 +
This module is a massive 37-volume compendium of writings of the early church fathers including
 +
  <reference osisRef="EarlyFathers:ANF01/Ignatius">Ignatius</reference>,
 +
  <reference osisRef="EarlyFathers:ANF01/Justin_Martyr">Justin Martyr</reference>,
 +
  <reference osisRef="EarlyFathers:ANF01/Irenæus">Irenaeus</reference>, and
 +
  <reference osisRef="EarlyFathers:TOC">many others</reference>.
 +
</p>
 +
</div>
 +
</pre>
 +
'''Note:'''
 +
<references />
 +
 
 +
===External Links===
 +
Links from one OSIS genbook to another OSIS genbook uses the same syntax as the internal links, above.
 +
 
 
==Images==
 
==Images==
 +
You can easily place images in your books using the <figure/> element. This element is "milestoned," meaning it isn't a container. The forward slash near the end signals that fact. Use the "src" attribute to define the location of the image relative to the compiled module. In the example below, the image "crosswire.jpg" resides in a folder "images" in the same folder as the compiled module.
 +
<pre><figure src="images/crosswire.jpg"/></pre>
 +
 
==Tables==
 
==Tables==
−
 
+
Tables require a bit of work to get set up but can be useful for some purposes. The entire table is contained in a <table> element, and each row is then contained in a <row> element. For each column in each row a <cell> element contains the text of that cell. The following table creates column labels in bold type and includes two columns and two rows below the label row.
 +
<pre><table>
 +
  <row>
 +
      <cell><hi type="bold">Column 1 Label</hi></cell>
 +
      <cell><hi type="bold">Column 2 Label</hi></cell>
 +
  </row>
 +
  <row>
 +
      <cell>Column 1, Row 1</cell>
 +
      <cell>Column 2, Row 1</cell>
 +
  </row>
 +
  <row>
 +
      <cell>Column 1, Row 2</cell>
 +
      <cell>Column 2, Row 2</cell>
 +
  </row>
 +
</table></pre>
 +
==Foreign Languages==
 +
Sometimes you may have multiple languages in a work, and in that case you should use the <nowiki><foreign></nowiki> element. That way if you have different fonts defined for different languages you are able to make the display more appropriate for the reader. A Hebrew example looks like this:
 +
<pre><foreign xml:lang="he">עִבְרִי</foreign>
 +
</pre>
 +
You have to define the language of the language that is foreign to the module's language using the "xml:lang" attribute.
 
=Example OSIS Genbook=
 
=Example OSIS Genbook=
 
The following is the text of a valid OSIS XML file which serves as a template for an OSIS Genbook for SWORD. Not all possible features are demonstrated here, but the file serves as an example of how to encode a Genbook. You should be able to copy the contents to a text editor, save it to a file as *.xml, and validate it against the OSIS schema.
 
The following is the text of a valid OSIS XML file which serves as a template for an OSIS Genbook for SWORD. Not all possible features are demonstrated here, but the file serves as an example of how to encode a Genbook. You should be able to copy the contents to a text editor, save it to a file as *.xml, and validate it against the OSIS schema.
Line 18: Line 155:
 
<pre><?xml version="1.0" encoding="UTF-8"?>
 
<pre><?xml version="1.0" encoding="UTF-8"?>
  
−
<osis xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace http://www.bibletechnologies.net/osisCore.2.1.1.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.bibletechnologies.net/2003/OSIS/namespace">
+
<osis xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace  
 +
      http://www.bibletechnologies.net/osisCore.2.1.1.xsd"  
 +
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
 +
      xmlns="http://www.bibletechnologies.net/2003/OSIS/namespace">
  
−
<osisText osisRefWork="book" xml:lang="en" osisIDWork="WorkID">
+
<osisText osisRefWork="GenBook" xml:lang="en" osisIDWork="WorkID">
 
<header>
 
<header>
 
<work osisWork="WorkID">
 
<work osisWork="WorkID">
 
<title>OSISGenbook</title>
 
<title>OSISGenbook</title>
−
<creator role="aut"/>
+
<creator role="aut">Author's Name</creator>
 
</work>
 
</work>
 
<work osisWork="Bible">
 
<work osisWork="Bible">
Line 100: Line 240:
 
<p>Default<hi type="sub">Subscript</hi>
 
<p>Default<hi type="sub">Subscript</hi>
 
</p>
 
</p>
−
<p>This is Hebrew: עִבְרִי.</p>
+
<p>This is Hebrew: <foreign xml:lang="he">עִבְרִי</foreign>.</p>
 
</div>
 
</div>
 
</div>
 
</div>
Line 108: Line 248:
 
</osis>
 
</osis>
 
</pre>
 
</pre>
 +
 +
= Making a Genbook module =
 +
'''xml2gbs''' (currently version 1.0) is the OSIS/ThML/TEI General Book module creation tool<ref>Use under Linux. The Windows edition has an undiagnosed bug that is not likely to be fixed soon.</ref> for the SWORD Project.
 +
  usage:
 +
  xml2gbs [-l] [-i] [-fT|-fO|-fE] <filename> [modname]
 +
  -l uses long div names in ThML files
 +
  -i exports to IMP format instead of creating a module
 +
  -fO, -fT, and -fE will set the importer to expect OSIS, ThML, or TEI format respectively
 +
    (otherwise it attempts to autodetect)
 +
'''Note:'''
 +
<references />
 +
 +
[[Category:Guides|OSIS Genbooks]]
 +
[[Category:OSIS]]
 +
[[Category:Genbook]]

Latest revision as of 10:21, 19 December 2020

Introduction

Much of what follows applies to any OSIS file, but there are a few features unique to genbooks (mainly in structure). This document aims to provide a complete, though not exhaustive, account of how to encode an OSIS genbook to become a SWORD module.

Keep in mind that, as with any XML document, elements are arranged hierarchically. The root node ends with the </osis> element, so the rest of the document occurs within that container. Within that is the Work node. Within that is the Header and then the Body of the text, which are parallel to each other. For a complete OSIS XML file, see Example OSIS Genbook below.

Root Node

The root node for a Genbook is the same as any other OSIS document. 

<?xml version="1.0" encoding="UTF-8"?>

<osis xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace 
      http://www.bibletechnologies.net/osisCore.2.1.1.xsd" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      xmlns="http://www.bibletechnologies.net/2003/OSIS/namespace">


</osis>

Work Container

The Work container for a Genbook is the same as any other OSIS document except the reference system (osisRefWork) is simply "GenBook". 

<osisText osisRefWork="GenBook" xml:lang="en" osisIDWork="WorkID">

</osisText>

Header

The Header should contain work elements for the current work and any other works to which this document links. In this example, the Bible is linked through Scripture references, and the KJV default reference scheme is used. More detailed information can be added, but the following is sufficient for a simple book with one author. 

<header>

<work osisWork="WorkID">
<title>OSISGenbook</title>
<creator role="aut">Author's Name</creator>
</work>

<work osisWork="Bible">
<refSystem>Bible</refSystem>
</work>

</header>

Body

Basic Structure

A <body> element is not used in OSIS. Instead, the body consists of <div> elements in a hierarchical structure. If you are encoding a collection of works by the same author, you can use the element <div type="bookGroup"> for the outer container. Otherwise start with <div type="book">. The following represents several levels of containers. 

<div type="book" osisID="Book">
   <div type="majorSection" osisID="majorSection 1">
      <div type="chapter" osisID="Chapter 1"> 
         <div type="section">
            <div type="subSection">
            </div>
         </div>
      </div>
   </div>
</div>

Of course you decide what is in the osisID (within the bounds of what the schema allows--basically you should stick to letters, numbers, and spaces), and the <title> element can be used to create titles for each chapter, etc. You may define your hierarchy to as much detail as you like. However, remember that readers of SWORD genbooks can only read one container at a time, so if you define lots of subsections it forces the reader to flip through them. If those parts are short, consider just adding section titles and limiting your containers to chapters for ease of reading.

Basic Formatting

Titles

Titles are defined using the <title> element: 

<title>Title Name</title>

Paragraphs

Paragraphs are defined using the <p> element. 

<p>Your paragraph goes here.</p>

Italic Text

For italics, use the <hi type="italic"> element. 

<hi type="italic">Italic text</hi>

Bold Text

To make text display in bold type, use the <hi type="bold"> element. 

<hi type="bold">Bold text</hi>

Superscript and Subscript

To make text superscript and subscript, just use the <hi> element with the type defined as "super" for superscript text and "sub" for subscript text. 

<hi type="super">Superscript text</hi>

<hi type="sub">Subscript text</hi>

Footnotes and Endnotes

Footnotes and endnotes are encoded in the same way except for their type name. Both use the <note> element. Using the "n" attribute you can define the number, letter, or symbol which you want to appear for the note, but not all front-ends will display that. 

<note type="x-footnote" n="1">Footnote text</note>

<note type="x-endnote" n="i">Endnote text</note>

Scripture References and Other Links

Scripture References

Scripture references may be encoded as links which some front-ends will use to open that reference in a Bible window. This is done using the <reference> element with the attribute "osisRef" defining the target verse or passage. Note the variety of possibilities for these kinds of references below. 

<reference osisRef="Gen.1.1">Genesis 1:1</reference>
<reference osisRef="Ps.119">Psalm 119</reference>
<reference osisRef="Prov.1-Prov.9">Proverbs 1-9</reference>
<reference osisRef="2Cor.6.14-2Cor.7.1">

Bible book names are those abbreviations found in the OSIS manual (they basically follow the SBL abbreviations), and each portion of the reference is separated by a period. In a range of verses the book and chapter must be repeated and separated by a dash.

Internal Links

Links from an OSIS module to a non-verse-keyed OSIS module should use an osisRef of the format[1]: 

Module:Div1/Div2/Div3

Hence, if the module EarlyFathers were OSIS[2], the introduction page may look like: 

<div type="section" osisID="Introduction">
<title>The Early Church Fathers Series</title>
<p>
This module is a massive 37-volume compendium of writings of the early church fathers including
  <reference osisRef="EarlyFathers:ANF01/Ignatius">Ignatius</reference>,
  <reference osisRef="EarlyFathers:ANF01/Justin_Martyr">Justin Martyr</reference>,
  <reference osisRef="EarlyFathers:ANF01/Irenæus">Irenaeus</reference>, and
  <reference osisRef="EarlyFathers:TOC">many others</reference>.
</p>
</div>

Note:

  1. ↑ Currently this syntax works but does not validate to osisCore.2.1.1.xsd
  2. ↑ It's actually ThML. Install from the Xiphos repository.

External Links

Links from one OSIS genbook to another OSIS genbook uses the same syntax as the internal links, above.

Images

You can easily place images in your books using the <figure/> element. This element is "milestoned," meaning it isn't a container. The forward slash near the end signals that fact. Use the "src" attribute to define the location of the image relative to the compiled module. In the example below, the image "crosswire.jpg" resides in a folder "images" in the same folder as the compiled module. 

<figure src="images/crosswire.jpg"/>

Tables

Tables require a bit of work to get set up but can be useful for some purposes. The entire table is contained in a element, and each row is then contained in a <row> element. For each column in each row a <cell> element contains the text of that cell. The following table creates column labels in bold type and includes two columns and two rows below the label row. 
<table>
   <row>
      <cell><hi type="bold">Column 1 Label</hi></cell>
      <cell><hi type="bold">Column 2 Label</hi></cell>
   </row>
   <row>
      <cell>Column 1, Row 1</cell>
      <cell>Column 2, Row 1</cell>
   </row>
   <row>
      <cell>Column 1, Row 2</cell>
      <cell>Column 2, Row 2</cell>
   </row>
</table>

Foreign Languages

Sometimes you may have multiple languages in a work, and in that case you should use the <foreign> element. That way if you have different fonts defined for different languages you are able to make the display more appropriate for the reader. A Hebrew example looks like this: 

<foreign xml:lang="he">עִבְרִי</foreign>

You have to define the language of the language that is foreign to the module's language using the "xml:lang" attribute.

Example OSIS Genbook

The following is the text of a valid OSIS XML file which serves as a template for an OSIS Genbook for SWORD. Not all possible features are demonstrated here, but the file serves as an example of how to encode a Genbook. You should be able to copy the contents to a text editor, save it to a file as *.xml, and validate it against the OSIS schema. 

<?xml version="1.0" encoding="UTF-8"?>

<osis xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace 
      http://www.bibletechnologies.net/osisCore.2.1.1.xsd" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      xmlns="http://www.bibletechnologies.net/2003/OSIS/namespace">

<osisText osisRefWork="GenBook" xml:lang="en" osisIDWork="WorkID">
<header>
<work osisWork="WorkID">
<title>OSISGenbook</title>
<creator role="aut">Author's Name</creator>
</work>
<work osisWork="Bible">
<refSystem>Bible</refSystem>
</work>
</header>

<div type="book" osisID="Book Title">
<title>Book Title</title>
<title type="x-author">Author's Name</title>
<p>Copyright</p>

<p>
<figure src="images/crosswire.jpg"/>
</p>

<div type="chapter" osisID="Chapter 1">
<p>This is Chapter 1, the introduction. 
<reference osisRef="Gen.1.1">Genesis 1:1</reference> is the first verse in the Bible. 
<reference osisRef="Rev.22.21">Rev 22:21</reference> is the last verse in the Bible. 
<reference osisRef="Ps.119">Psalm 119</reference> is the longest chapter in the Bible. 
<reference osisRef="Prov.1-Prov.9">Proverbs 1-9</reference> introduce the book of Proverbs. 
<reference osisRef="John.1-John.1.18">John 1:1-18</reference> introduces the book of John. 
<reference osisRef="2Cor.6.14-2Cor.7.1">2 Corinthians 6:14-7:1</reference> teaches about holiness.
</p>

<div type="section">
<title>Section 1</title>
<p>This is chapter 1, section 1.</p>
<table>
<row>
<cell>
<hi type="bold">Column 1 Label</hi>
</cell>
<cell>
<hi type="bold">Column 2 Label</hi>
</cell>
</row>
<row>
<cell>Column 1, Row 1</cell>
<cell>Column 2, Row 1</cell>
</row>
<row>
<cell>Column 1, Row 2</cell>
<cell>Column 2, Row 2</cell>
</row>
</table>
</div>

<div type="section">
<title>Section 2</title>
<p>This is chapter 1, section 2.<note type="x-footnote" n="1">Footnote</note>
</p>
</div>
</div>

<div type="chapter" osisID="Chapter 2">
<p>This is Chapter 2, the introduction.<note type="x-endnote" n="i">Endnote</note>
</p>

<div type="section">
<title>Section 1</title>
<p>This is chapter 2, section 1.</p>
</div>

<div type="section">
<title>Section 2</title>
<p>This is chapter 2, section 2.</p>
<p>Default <hi type="italic">Italics</hi>
</p>
<p>Default <hi type="bold">Bold</hi>
</p>
<p>Default<hi type="super">SuperScript</hi>
</p>
<p>Default<hi type="sub">Subscript</hi>
</p>
<p>This is Hebrew: <foreign xml:lang="he">עִבְרִי</foreign>.</p>
</div>
</div>

</div>
</osisText>
</osis>

Making a Genbook module

xml2gbs (currently version 1.0) is the OSIS/ThML/TEI General Book module creation tool[1] for the SWORD Project. 

 usage:
  xml2gbs [-l] [-i] [-fT|-fO|-fE] <filename> [modname]
 -l uses long div names in ThML files
 -i exports to IMP format instead of creating a module
 -fO, -fT, and -fE will set the importer to expect OSIS, ThML, or TEI format respectively
   (otherwise it attempts to autodetect)

Note:

  1. ↑ Use under Linux. The Windows edition has an undiagnosed bug that is not likely to be fixed soon.
Retrieved from "https://wiki.crosswire.org/index.php?title=OSIS_Genbooks&oldid=17002"