Permalink
Browse files

Initial 3.0.rc1 release notes.

  • Loading branch information...
klassenjm committed Sep 9, 2016
1 parent f8f4006 commit 8c9afb204f99d61caf780a51697ab64987b9654b
Showing with 71 additions and 31 deletions.
  1. +14 −25 docs/about/index.rst
  2. +52 −1 docs/about/releasenotes.rst
  3. +1 −1 docs/index.rst
  4. +3 −3 docs/lists/index.rst
  5. +1 −1 docs/tables/index.rst
View
@@ -20,45 +20,34 @@ Introduction
What are Standard Format Markers?
---------------------------------
In general terms, a markup language is a special notation for identifying the components and structure of an electronic document. It combines extra information about the text together with the text itself. The extra information is what is expressed using markup. Markup can also include information about the intended presentation of the text, or instructions for how a software process should handle the text. A good markup system is easily identified as separate from the text itself.
A markup language is a special notation for identifying the components and structure of an electronic document. It combines meta information about the text together with the text itself. The meta information is what is expressed using markup. Markup can also include information about the intended presentation of the text, or instructions for how a software process should handle the text. A good markup system is easily identified as separate from the text itself.
Standard Format Markers have been used for many years within the Bible translation community as a method for identifying the unique textual elements which exist within an electronic scripture document. SFMs start with a backslash character ``\`` and end with the next space. Over time many different local "standards" for SFM use were developed, adapted, and used, for supporting the varied requirements of Bible translation and publishing projects around the globe.
Standard Format Markers (SFMs) have been used for many years within the Bible translation community as a method for identifying the unique textual elements within a digital scripture text. Generally, SFMs start with a backslash character ``\`` and end with the next space. Over years many different local "standards" for SFM use were developed, adapted, and used for supporting the varied requirements of Bible translation and publishing projects in different areas of the world.
.. _about_usfm_history:
.. index:: pair: USFM; history
History of USFM
---------------
The divergent use of SFMs led to a variety of problems – most notably the challenges associated with sharing text or related text processing tools among entities, departments, or partner organizations. Separate and ongoing maintenance of duplicated tools and procedures, which were required for managing the flow of the text through its life-cycle, became costly and very difficult to support.
The diverging use of SFMs led to various problems – most notably the challenge associated with sharing text or text processing tools between organization departments or with partnering organizations. Maintenance of software tools and procedures for handling texts using differing collections of SFMs became costly and difficult to support.
In March 2002 a working group was established within the `United Bible Societies <http://unitedbiblesocieties.org>`_ with the mandate of "crafting a unified specification for SFM use across 4 UBS areas". Having one SFM standard would provide numerous benefits:
In March 2002 a working group was established within the `United Bible Societies <http://unitedbiblesocieties.org>`_ with the mandate of producing a unified specification for SFM use across 4 UBS areas.
* Allow more thought and effort to be put into developing just one set of tools and utilities to be shared by all projects:
- Tools for text checking and analysis.
- Tools for developing supporting textual resources such as concordances and indexes.
- Tools for streamlining the publishing process.
* Eliminate or minimize duplication of effort in providing these tools.
* Allow better sharing of both tools and data.
* Allow Paratext users to use one tested and proven stylesheet.
* Prepare the project for a smoother transition to other markup formats or future technologies.
Ideally an SFM standard would have as one of its goals that of marking common scriptural element types, and not formatting (presentation) information. USFM has attempted to unify a long history of SFM type scripture markup implementations, some of which were more or less strict in their tolerance for format-oriented markers. The primary focus in USFM development was on unification, not markup creation. What this means is that USFM inherits support for both the positive, and some negative, aspects of pre-existing SFM marker use. The USFM working group did not wish to create an unmanageable conversion task for legacy SFM encoded texts.
Ideally an SFM standard would seek to identify and mark all common scriptural element types, and avoid markup primarily for formatting (presentation) information. USFM has attempted to unify a long history of SFM scripture markup implementations, some of which were more or less strict in their tolerance for format-oriented markers. USFM development focuseed primarily on unification, not new markup creation. Practically speaking, this means is that USFM inherits support for both the positive, and some negative, aspects of pre-existing SFM marker use.
.. _about_usfm_unification:
.. index:: USFM; unification notes
Unification Notes
-----------------
* Markers which would be used in a broader text "environments" were named using a reserved initial letter, rather than an opening and closing tag:
* Markers which would be used in specific text "environments" are named using a reserved initial letter:
- ``\i`` - Introductions
- ``\f`` - Footnotes
- ``\x`` - Cross references
- ``\e`` - Explanatory (study) material - for extended notes, sidebars and bridge materials.
* Related marker types were often consolidated using “numbered” marker definitions.
* Related marker types were usually consolidated using “numbered” marker definitions.
- Example: ``\mt#``, ``\ms#``, ``\s#``, ``\li#`` etc., where the variable # represents a number which can indicate a level or relative weighting.
@@ -70,21 +59,21 @@ Unification Notes
Software Notes
--------------
* Translation editors which implement support for USFM encoded text may provide a formatted view of the text using a set of style definitions for each USFM marker. These "stylesheets" most often refer to these formatting definitions as *paragraph* and *character* styles.
* In USFM, character level markup can be nested (embedded) within a paragraph element, or another character element. However, software applications will not necessarily be capable of rendering all of the display variations which may be implied due to marker nesting.
* Translation editors which implement support for USFM encoded text may provide a formatted view of the text using a set of style definitions for each USFM marker. These "stylesheets" typically refer to these formatting definitions as *paragraph* and *character* styles.
* In USFM, character level markup exists within a paragraph element, or can be :doc:`nested </characters/nesting>` (embedded) within another character element. Software applications will not necessarily be capable of rendering all of the display variations which may be implied due to marker nesting.
.. _about_usfm_changes:
.. index:: USFM; change management
Change Management
-----------------
Over the course of its development it has become clear that the USFM standard will not likely include and handle markup for all potential (real or perceived) markup needs which a project may require. There are a number of reasons for this, which include:
The USFM standard will not necessarily include markup for all potential (real or perceived) markup needs which a project may require. There are a number of reasons for this, including:
* **The intention of keeping the USFM marker inventory manageable** from a typical end user's perspective. |br| Some may argue that the more than 180 existing marker possibilities are already more than challenging enough to select from and use correctly. For this reason a "draft" stylesheet was created for Paratext editing which lists only the essential markers for editing a typical translation's 1st draft text. |br| |br|
* **The intention to encourage content oriented markup.** |br| Although USFM contains markers which are format (presentation) oriented (see History of USFM), the use of these is typically discouraged, wherever an suitable alternative is available. |br| |br|
* **The intention to maintain a stable target for tool developers.** |br| The USFM marker inventory cannot continue to evolve and develop indefinitely without minimizing the benefit it potentially offers to developers working on text checking, analysis, conversion, and publishing tools. A stable target is needed for these tools to work against.
* The intent to keep the size of the USFM marker inventory manageable.
* The intention to encourage content oriented markup. |br| Although USFM contains some markers which are format (presentation) oriented (see History of USFM), the use of these is typically discouraged, wherever an suitable alternative is available.
* The intention to maintain a stable target for tool developers.
Since USFM 1.0, requests for additions to the standard have been received and considered by the USFM committee (see Release Notes for some details). The committee has made a choice to specifically exclude new markers submissions that specify formatting from becoming part of USFM. What this means is that the USFM standard is open to the consideration of new markup needs, but closed to allowing new format oriented markup. At times this position has caused some frustration for users who might otherwise be quite satisfied with USFM, but would be greatly assisted by adding markup to their text which is not a part of the standard.
Since USFM 1.0, requests for additions to the standard have been received and considered by a USFM maintenance committee (see :doc:`Release Notes </about/releasenotes>` for some details).
|ico_See| See also: User extension :ref:`\\z namespace <syntax_znamespace>`.
@@ -11,6 +11,57 @@ Release Notes
-----
.. _about_release_3.0:
3.0
^^^
*September 2016*
USFM 3.0 additions or revisions are highlighted throughout this documentation using the badge |badge_3.0|
**Marker Additions**
* Letter opening: :ref:`\\po <usfmp_po>`
* List header and footer elements: :ref:`\\lh <usfmp_lh>` and :ref:`\\lf <usfmp_lf>`
* Embedded list: :ref:`\\lim# <usfmp_lim#>`
* Hebrew note: :ref:`\\qd <usfmp_qd>`
* `Open discussion <https://github.com/ubsicap/usfm/issues/7>`_ - Translator's chunk marker
* Aramaic wordlist entry: :ref:`\\wa ...\\wa\* <usfmc_wa>`
* Geographic proper name (Chinese texts): :ref:`\\png ...\\png\* <usfmc_png>`
* Target references "added" text: :ref:`\\xta ...\\xta\* <usfmc_xta>`
* Published cross reference origin text: :ref:`\\xop ...\\xop\* <usfmc_xop>`
* Structured list items: :ref:`\\lik ...\\lik\* <usfmc_lik>` and :ref:`\\liv# ...\\liv#\* <usfmc_liv#>`
* List item total: :ref:`\\litl ...\\litl\* <usfmc_litl>`
* Semantic division: :ref:`\\sd# <usfmp_sd#>`
* Link text: :ref:`\\jmp ...\\jmp\* <usfmc_jmp>`
* Common peripheral :ref:`identifiers <periph_div>`.
* Ruby annotations (CJK texts): :ref:`\\rb ...\\rb\* <usfmc_rb>` and :ref:`\\rt ...\\rt\* <usfmc_rt>`
**Marker Revisions**
* Support citation form for wordlist / glossary text (update :ref:`\\w ...\\w\* <usfmc_w>`).
* Support for explicit :ref:`table cell <usfmc_tc#>` column :ref:`spanning <usfmc_table_colspan>`.
* Revised syntax for figures / illustrations applying descriptive :doc:`attributes </characters/attributes>`: :ref:`\\fig ...\\fig\* <usfmc_fig-attr>`
* *Deprecate* cross reference and footnote DC content markers: :ref:`\\xdc ...\\xdc\* <usfmc_xdc>` and :ref:`\\fdc ...\\fdc\* <usfmc_fdc>`
* *Deprecate* combined marker for proper name within translator's addition: :ref:`\\addpn ...\\addpn\* <usfmc_addpn>`
* *Deprecate* numbered running header: :ref:`\\h# <usfmp_h>`
* *Deprecate* pronunciation info marker: :ref:`\\pro ...\\pro\* <usfmc_pro>` in favour of :ref:`ruby annotations <usfmc_rb>` proposal.
**Syntax and Features**
* Syntax for assigning word-level descriptive :doc:`attributes </characters/attributes>`.
- Descriptive attributes for :ref:`\\w ...\\w\* <usfmc_w-attr>`
- Descriptive attributes for :ref:`\\fig ...\\fig\* <usfmc_fig-attr>`
* Syntax for assigning word-level linking :doc:`attributes </characters/linking>`.
* Syntax for peripheral (:doc:`\\periph </peripherals/index>`) :ref:`identifiers <periph_id>`.
**Standard Reference**
* Clarify and document specification regarding :ref:`whitespace <syntax_whitespace>` and :ref:`new lines <syntax_newline>`.
.. _about_release_2.5:
2.5
@@ -57,7 +108,7 @@ Version numbers for the base USFM stylesheet and the study Bible notes and sideb
* Added study Bible cross reference marker :ref:`\\ex <usfmn_ex>` for adding additional cross-references to the notes project.
Marker Revisions
**Marker Revisions**
* *DEPRECATED* - Study Bible footnote marker ``\fs`` for marking a footnote summary text.
* Permit cross references to be added to the study Bible notes project.
View
@@ -38,4 +38,4 @@ USFM Documentation
.. Character Marker Attributes <characters/attributes>
Linking <characters/linking>
|ico_See| *See also* the documentation :ref:`Index <genindex>` page.
|ico_See| *See also* the documentation :ref:`Index <genindex>` page and :doc:`Release Notes <about/releasenotes>`.
View
@@ -189,7 +189,7 @@ Lists
-----
.. _usfmc_lit:
.. _usfmc_litl:
.. index:: marker; \litl ...\litl*, lists; list entry total
\\litl ...\\litl\*
@@ -252,7 +252,7 @@ Standard USFM :doc:`table </tables/index>` structures can be challenging to disp
Structured lists are not strictly a replacement for table markup, but may prove to be a more flexible option for some types of tabular content.
Character marker pairs :ref:`\\lk ...\\lk\* <usfmc_lik>` and :ref:`\\lv# ...\\lv#\* <usfmc_liv>` mark the content of list entries (:ref:`\\li <usfmp_li#>`) which are essentially a key + value pair. A key may have multiple values.
Character marker pairs :ref:`\\lik ...\\lik\* <usfmc_lik>` and :ref:`\\liv# ...\\liv#\* <usfmc_liv#>` mark the content of list entries (:ref:`\\li <usfmp_li#>`) which are essentially a key + value pair. A key may have multiple values.
-----
@@ -271,7 +271,7 @@ Character marker pairs :ref:`\\lk ...\\lk\* <usfmc_lik>` and :ref:`\\lv# ...\\lv
-----
.. _usfmc_liv:
.. _usfmc_liv#:
.. index:: marker; \liv# ...\liv#*, lists; list entry value
\\liv# ...\\liv#\*
View
@@ -134,5 +134,5 @@ Numbers 2.10-16 (GNT)
.. warning::
Empty table cells:
**Empty table cells:**
An empty table cell still requires a corresponding marker in the table text. Alternatively, indicate that a cell spans multiple columns by indicating a column range ``\tr \tcr1-2 Total: \tcr3 151,450``.

0 comments on commit 8c9afb2

Please sign in to comment.