View source for List of eXtensions to OSIS used in SWORD

== Purpose ==
This page is intended to be a one-stop reference which lists all the extensions to OSIS either recognized by the SWORD API or (at least) also found in various SWORD modules. It will also include the extensions capable of being generated by some of our conversion scripts.

Whether or not any particular extension is supported by SWORD can only be determined by reading the source code.

== Introduction ==
The OSIS reference standard permits custom extensions to XML elements in the form of ''attribute values'' with the prefix '''x-'''. <ref>In rarer cases, the x-prefix has been used to define an ''attribute name'' or even an ''element name''.</ref>

Several such extensions are already in use by the SWORD API.<BR>Some of these are designed to facilitate solutions (or workarounds) to particular requirements that arise in the course of module creation.<ref>Not all front-end applications support these extensions to OSIS. For some further details, refer to [[Choosing a SWORD program]].</ref>

'''Notes:'''
<references />

== The list ==
:''This list may be incomplete. When adding extensions to this page, please keep them in alphabetical order.<BR>State clearly which OSIS element and attribute they apply to, and most importantly, include any rules that govern their proper use.<BR>If any are now deprecated for use in new modules, please mention this status, even though existing modules may have made use thereof.<BR>For extensions where the SWORD support is unclear, it may be better to add them to the talk page.<BR>A few of these extensions are essentially methods to record metadata, and have no effect on the module display.''

=== x-1, x-2, etc ===
These can be used within the '''seg''' element as a value of the attribute '''subType'''. 

They are used along with <tt>type="x-variant"</tt> to identify whether the reading is the primary or secondary variant. See [[OSIS Bibles#Marking_variants|marking variants]].


These can also be used within the '''w''' element as a value of the attribute '''subType'''.

They are used along with <tt>type="x-split"</tt>, for which see below.

=== x-added ===
This can be used within the '''seg''' element as a value of the attribute '''subType'''.

It can be used as a workaround for places where the text added by the translator is within a '''w''' element. See note in [[OSIS Bibles#Recommended_approach|OSIS Bibles]].

=== x-begin-paragraph ===
This can be used within the '''lb''' element as a value of the attribute '''type'''.

It's used in some modules as an alternative to using the paragraph element '''p'''. See also '''x-end-paragraph''' below.

=== x-big ===
This can be used within the '''seg''' element as a value of the attribute '''type'''.

It is used in some Hebrew Bible modules to determine that the segment of text should be displayed with a larger font size than the main text.

=== x-br ===
This can be used within the '''lb''' element as a value of the attribute '''type'''.

''It does not add anything significant to the line breaks, and seems to be used to distinguish simple line breaks from those at the start & end of paragraphs in some modules.''

=== x-center ===
This can be used within the '''p''' element as a value of the attribute '''type'''.

It may be used to mark a centered paragraph. It corresponds to the USFM marker '''\pc'''

=== x-centered ===
This can be used within the '''l''' element as a value of the attribute '''type'''.

It may be used to mark a centered line of poetry.

=== x-chapterLabel ===
This can be used within the '''title''' element as a value of the attribute '''subType'''. 

It should be used along with "chapter" as the value of the attribute '''type'''. This ensures that the SWORD engine treats chapter labels in the same way as chapter headings.

It corresponds with the USFM marker '''\cl''' when used ''after'' the chapter marker '''\c'''

=== x-comments-to ===
This can be used in the '''rights''' element as a value of the attribute '''type'''.

It's used to mark the email address for enquiries regarding the distribution license. 
See also '''x-license''' and '''x-license-URL''' below.

=== x-copyright ===
This can be used in the '''rights''' element as a value of the attribute '''type'''.

It's used to embed the copyright information, i.e. in addition to what may be stated in the module conf file.

=== x-embedded ===
This can be used within the '''p''' element as a value of the attribute '''type'''. It corresponds to the USFM marker '''\pm'''

==== x-embedded-closing ====
This can be used within the '''p''' element as a value of the attribute '''type'''. It corresponds to the USFM marker '''\pmc'''

==== x-embedded-opening ====
This can be used within the '''p''' element as a value of the attribute '''type'''. It corresponds to the USFM marker '''\pmo'''

=== x-end-paragraph ===
This can be used within the '''lb''' element as a value of the attribute '''type'''.

It's used in some modules as an alternative to using the paragraph element '''p'''. See also '''x-begin-paragraph''' above.

=== x-extra-p ===
This can be used within the '''milestone''' element as a value of the attribute '''type'''.

It is used (for example) in the KJV module to mark an extra paragraph break in places where the printed edition does not have a [http://en.wikipedia.org/wiki/Pilcrow pilcrow].<BR>''Most front-ends do not support this feature''.

=== x-glossary ===
This can be used within the '''reference''' element as a value of the attribute '''type'''.

It may be used to link references to items in an ancillary glossary module, and should be accompanied by a valid '''osisRef''' attribute.<BR>See the [[Choosing a SWORD program#Module_Support|module support]] table in the comparison of notable front-end applications.

=== x-importer ===
This can be used within the '''milestone''' element as a value of the attribute '''type'''.

It appears in the testament heading(s). Along with <tt>subType="x-osis2mod"</tt> it's used solely for traceability, being generated automatically by recent versions of <tt>osis2mod</tt>.<BR>
The '''n''' attribute within this milestone element identifies the version of the SWORD utility by which the module was created. e.g.

 <milestone type="x-importer" subType="x-osis2mod" n="$Rev: 2562 $"/>

=== x-indented-# ===
These can be used as the '''type''' attribute value of the paragraph element '''p'''. They specify an indented paragraph, where '''#''' = 1 to 5 is the indentation level. These type of paragraph markers are among those converted from USFM by the Python script usfm2osis.py

=== x-intro ===
This can be used within the '''title''' element as a value of the attribute '''type'''.

It may be used to identify a title for a Bible book introduction. See [[Frontends:FeatureList#Module_support|module support]].

=== x-level-1, x-level-2, etc ===
These can be used within the '''milestone''' element as a value of the attribute '''subType'''. 

These are used along with the attribute <tt>type="cQuote"</tt> to mark the quote level within a continuation quote passage. Up to 4 quote levels are supported by SWORD.

=== x-license ===
This can be used within the ''milestone'' form of the '''div''' element as a value of the attribute '''type'''. 

It's used to embed a distribution license within the module itself (i.e. in addition to whatever is stated in the conf file).<BR>
For example, it's found in the module SBLGNT, immediately after the '''titlePage''' element.


This can also be used in the '''rights''' element as a value of the attribute '''type'''.

This is to be preferred, as it makes use of the element in the OSIS standard that was intended for this very purpose.

=== x-license-url ===
This can be used in the '''rights''' element as a value of the attribute '''type'''.

It's used to mark the URL for the distribution license information.

=== x-milestone ===
This can be used for the ''milestone'' form of the '''div''' element as a value of the attribute '''type'''.

It's used (e.g.) along with the attribute <tt>subType="x-preverse"</tt>, for which see below. An example is the module JPS.

=== x-nobreak ===
This can be used within the '''p''' element as a value of the attribute '''type'''. 

It can be used to indicate "no-break" with previous paragraph (regardless of previous paragraph type). It is commonly used in cases where the previous paragraph spans the chapter boundary. It corresponds to the USFM marker '''\nb'''

=== x-noindent ===
This can be used within the '''p''' element as a value of the attribute '''type'''. 

It can be used to mark a paragraph flush left, with no indentation. It corresponds to the USFM marker '''\m'''

==== x-noindent-indented ====
This can be used within the '''p''' element as a value of the attribute '''type'''. 

It can be used to mark an indented paragraph flush left. It corresponds to the USFM marker '''\mi'''

=== x-osis2mod ===

See above under '''x-importer'''.

=== x-p ===
This can be used within the '''milestone''' element as a value of the attribute '''type'''.

It may be used along with the attribute <tt>marker="¶"</tt> to include the [http://en.wikipedia.org/wiki/Pilcrow pilcrow] sign as a visible paragraph marker, as (for example) found in the KJV module.

=== x-preverse ===

This can be used within the '''title''' element as a value of the attribute '''subType'''.

It provides a means to correctly display a title just before the current verse. For proper use, the title element must occur ''within'' the '''verse''' element, or (for milestoned OSIS) ''after'' the verse sID milestone and ''before'' the eID milestone for the same verse or verse range. Failure to adhere to this rule can have the adverse effect of making the title display before the previous verse, or (worse still) in the previous chapter.


It can also be used within the ''milestone'' form of the '''div''' element as a value of the attribute '''subType'''.

This is provides support for content associated with a verse, that should be displayed before the verse marker. These used to be called "preverse title" or "preverse heading". We agreed a while back to generalize this concept to simply be called a 'preverse div'. Other things besides a single title might be shown before a verse.<BR>''Support became official in SWORD release version 1.7.2 &ndash; the syntax is present in module KJV 2.7 in CrossWire Main, where it's used for the canonical Psalm titles. The syntax is absent from the source OSIS XML file, it being generated automatically by osis2mod.''

=== x-right ===
This can be used within the '''l''' element as a value of the attribute '''type'''.

It may be used to mark a right aligned line of poetry, which may be useful for poetical text in a module that uses a RtL script.<BR>
If the use of '''x-selah''' is insufficient, this may also help in LtR languages for proper placement of the word translated from the Hebrew, usually transliterated as ''Selah'' in some English Bibles.

It can also be used within the '''p''' element as a value of the attribute '''type'''. It is used to specify a right aligned paragraph. It corresponds to the USFM marker '''\pr'''

=== x-selah ===
This can be used within the '''foreign''' element as a value of the attribute '''type'''.

It's used in several of the Psalms (also in Habakkuk) to mark the Hebrew word (transliterated to English as) ''Selah''.

This extension is deprecated, even though it's found in the ESV module.

The OSIS standard already provides a means to mark ''Selah'' within poetry markup.

 <l type="selah">Selah</l>

However, this currently forces the ''Selah'' to a new poetry line, which some front-ends can right align.

=== x-small ===
This can be used within the '''seg''' element as a value of the attribute '''type'''.

It is used in some Hebrew Bible modules to determine that the segment of text should be displayed with a smaller font size than the main text.

=== x-speaker ===
This can be used within the '''title''' element as a value of the attribute '''type'''.

It's used to mark each of the speakers in some translations of the Song of Songs.<BR>
This extension is deprecated. The OSIS standard already has two methods to identify speakers in association with a castlist.

=== x-split ===
This can be used within the '''w''' element as a value of the attribute '''type'''. 

It's used to mark a lemma in places where the translation text splits the word of the original language.<BR>It's used along with an appropriate '''subType''' attribute numerical value such as '''x-1''', '''x-2''', etc. For usage examples, see the KJV module.

=== x-Strongs:... ===

This can be used within the '''w''' element as a value of the attribute '''lemma'''. 

The colon is followed by the Strongs reference(s).

=== x-StrongsMorph:... ===
This can be used within the '''w''' element as a value of the attribute '''morph'''.

The colon is followed by the morphology reference.

=== x-strongsMarkup ===
This could be used within the '''milestone''' element as a value of the attribute '''type'''.

It was used in the KJV module merely to track editing changes to the XML. It has no effect on the displayed text. Now deprecated.

=== x-sub ===
This can be used within the '''title''' element as a value of the attribute '''type'''. 

It is used to mark subsections within the Biblical text.

=== x-subSubSection ===
This can be used within the ''milestone'' form of the '''div''' element as a value of the attribute '''type'''. 

For example, it's used in the ABN module to mark the start & end of the acrostic stanza divisions in Psalm 119 and similar passages.
<ref>Currently, this feature is commented out in <tt>usfm2osis.pl</tt>.</ref>

=== x-suspended ===
This can be used within the '''seg''' element as a value of the attribute '''type'''.

It is used in some Hebrew Bible modules to determine that the segment of text should be displayed with a smaller font size than the main text, but with the top of the letters flush with the top of letters in the main text.

=== x-testament ===
This can be used within the '''div''' element as a value of the attribute '''type'''. 

This may be used to indicate one of the two traditional top-level major text divisions of a Bible. See [[OSIS Tutorial#Text_Divisions|Text Divisions]].<BR>It is functionally equivalent to the type attribute value '''bookGroup'''. See [[OSIS Bibles#Body|body]] under the general structure for OSIS Bibles.

=== x-trademark ===
This can be used within the ''milestone'' form of the '''div''' element as a value of the attribute '''type'''. 

It's used to embed a registered trademark within the module itself (i.e. in addition to whatever is stated in the conf file).<BR>
For example, it's found in the module LEB, after the '''titlePage''' element.

=== x-transChange ===
This can be used within the '''seg''' element as a value of the attribute '''type'''.

It can be used as a workaround for places where the text added by the translator is within a '''w''' element. See note in [[OSIS Bibles#Recommended_approach|OSIS Bibles]].

=== x-unit ===

The '''div''' attribute '''x-unit''' provides a level of division between book and chapter. It is sometimes used in '''GenBook''' modules.

=== x-unparagraphed ===
This can be used within the '''lb''' element as a value of the attribute '''type'''. 

It's used in some modules to indicate that the line breaks were added solely to improve presentation.<ref>The usefulness of these line breaks is in those front-end applications which do not have an option to show each verse on a separate line.<br>The lb element would normally be included at the end of every verse in the module.<br>This prevents each chapter being displayed as a single unbroken paragraph. The type attribute merely clarifies the purpose of the line breaks.</ref><br>
E.g. for modules where the available source text is entirely without paragraphing information.

:Example: module '''Geneva1599''' version 2.0

=== x-variant ===

This can be used within the '''seg''' element as a value of the attribute '''type'''. 

It can be use for marking variants present in different versions of a text. See [[OSIS Bibles#Marking_variants|marking variants]].

== eXtensions generated by usfm2osis.py ==

In 2012, [[user:Osk|Osk]] released a Python script to [[Converting SFM Bibles to OSIS#usfm2osis.py|convert USFM to OSIS]]. In 2015, the script was moved to [https://github.com/refdoc/Module-tools GitHub].

Here is a list of all the OSIS eXtensions capable of being generated by usfm2osis.py

'''Extracted eXtensions''': (where # is short for an integer value, 1 to 5)
<pre>
x-alphabeticalContents
x-center
x-chapterLabel
x-chronology
x-description
x-dotUnderline
x-embedded
x-embedded-closing
x-embedded-opening
x-end
x-foreword
x-glossary
x-halfTitlePage
x-indent-#
x-indented
x-indented-#
x-indented-hanging
x-introduction
x-introduction-end
x-level-#
x-liturgical
x-mapIndex
x-nobreak
x-nobreakNext
x-nobreakNext-indented
x-noindent
x-noindent-indented
x-noindent-quote
x-ntQuotesfromLXX
x-optional
x-p
x-promotionalPage
x-quote
x-right
x-sidebar
x-speaker
x-spine
x-study
x-subSubSection
x-subSubSubSection
x-subSubSubSubSection
x-tableofAbbreviations
x-to-next-level
x-unknown
x-usfm-ie
x-usfm-sts
x-usfm-toc1
x-usfm-toc2
x-usfm-toc3
x-usfm-z-\1
x-weightsandMeasures
x-workTitle
</pre>
In addition to those listed above, the script can also output these subType attributes for introductions:
<pre>
x-acts
x-bible
x-deuterocanon
x-epistles
x-gospels
x-history
x-letters
x-newTestament
x-oldTestament
x-pentateuch
x-poetry
x-prophecy
</pre>

'''Notes:'''
# This list provides a suitable reference for when updates are to be be made on the SWORD tool osis2mod as well as SWORD itself.
# Further edits to this section are required to document the intended usage for each listed eXtension.
# In <tt>x-usfm-z-\1</tt>, the \1 substitutes for the name of any user defined USFM tag found in the Paratext files.
# It seems that <tt>x-p</tt> is used only as a temporary attribute within the script, and removed during the osisReorderAndCleanup.
# The list was extracted from usfm2osis.py with "Id: usfm2osis.py 492 2015-05-21 11:54:55Z refdoc ".
# That version of the script refers to usfmVersion = '2.35' even though the latest USFM version is 2.40

== eXtensions generated by adyeths/u2o.py==
:''To be documented''

== End notes ==
<references />

[[Category:OSIS|Listof eXtensions to OSIS used in SWORD]]
[[Category:Documentation|Listof eXtensions to OSIS used in SWORD]]