Permalink
Browse files

Update .. index:: texts to ensure that items are categorized well

  • Loading branch information...
klassenjm committed Sep 9, 2016
1 parent 91a99df commit 59937af473c14971a74f149a7f6b0068c9141a83
View
@@ -1,6 +1,7 @@
.. include:: /_static/inc_styles.txt
.. index:: introduction, about, USFM (about)
.. index:: introduction
pair: USFM; about
************
Introduction
@@ -24,7 +25,7 @@ In general terms, a markup language is a special notation for identifying the co
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.
.. _about_usfm_history:
.. index:: USFM (history)
.. index:: pair: USFM; history
History of USFM
---------------
@@ -46,7 +47,7 @@ In March 2002 a working group was established within the `United Bible Societies
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.
.. _about_usfm_unification:
.. index:: USFM (unification notes)
.. index:: USFM; unification notes
Unification Notes
-----------------
@@ -64,7 +65,7 @@ Unification Notes
* Marker definition "collisions" were resolved (same marker used to mark different content).
.. _about_usfm_software:
.. index:: USFM (software notes)
.. index:: USFM; software notes
Software Notes
--------------
@@ -73,7 +74,7 @@ Software Notes
* 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.
.. _about_usfm_changes:
.. index:: USFM (change management)
.. index:: USFM; change management
Change Management
-----------------
@@ -88,8 +89,8 @@ Since USFM 1.0, requests for additions to the standard have been received and co
|ico_See| See also: User extension :ref:`\\z namespace <syntax_znamespace>`.
.. _about_usfm_sty:
.. index:: stylesheets (ParaTExt)
.. index:: pair: stylesheet; ParaTExt
ParaTExt Stylesheets
--------------------
The most recent full and draft USFM stylesheet files for use with the ParaTExt translation editor are always available from http://paratext.org/usfm.
ParaTExt Stylesheet
-------------------
The most recent full and draft USFM stylesheet file for use with the ParaTExt translation editor are always available from http://paratext.org/usfm.
View
@@ -11,7 +11,7 @@ Syntax Notes
-----
.. _syntax_general:
.. index:: syntax (general)
.. index:: syntax; general
General Syntax
--------------
@@ -24,7 +24,7 @@ General Syntax
* For marker pairs (character and note), the opening marker ends with the next space character (as with paragraph markers). The matching closing marker is identical to the opening marker but ends with an asterisk character ``*``. Example: ``\w grace\w*``.
.. _syntax_numberedMarkers:
.. index:: syntax (numbered markers)
.. index:: syntax; numbered markers
Numbered Markers
----------------
@@ -41,7 +41,7 @@ Some USFM markers include an optional numeric variable, which is represented in
The variable # should not be used to indicate a specific occurrence in scripture of the element type (e.g. using \\s3 to represent the location of the particular section heading before the "Story of Creation" in Genesis 1.)
.. _syntax_endmarkerInNotes:
.. index:: syntax (endmarkers in notes)
.. index:: syntax; endmarkers in notes
Endmarkers in Footnotes and Cross References
--------------------------------------------
@@ -61,7 +61,7 @@ A. ``\f + \fr 2.4 \fk The \nd Lord\nd*: \ft See \nd Lord\nd* in Word List.\f*``
B. ``\f + \fr 2.4\fr* \fk The \nd Lord\nd*:\fk* See \nd Lord\nd* in Word List.\f*``
.. _syntax_whitespace:
.. index:: syntax (whitespace)
.. index:: syntax; whitespace, whitespace
Whitespace
----------
@@ -79,7 +79,7 @@ USFM considers space (U+0020), tab (U+0009), and :ref:`newline characters <synta
- Multiple whitespace preceding a :doc:`paragraph </paragraphs/index>` marker.
.. _syntax_newline:
.. index:: syntax (newline)
.. index:: syntax; newline, newlines
Newlines
^^^^^^^^
@@ -89,7 +89,7 @@ USFM processors should treat the single CR (U+000D) or LF (U+000A) characters,
All paragraph markers should be preceded by a single newline.
.. _syntax_whitespace_normalization:
.. index:: syntax (whitespace)
.. index:: pair: whitespace; normalization
Whitespace Normalization
^^^^^^^^^^^^^^^^^^^^^^^^
@@ -102,7 +102,7 @@ Whitespace Normalization
* Normalized whitespace preceding the closing marker of a character or note marker pair is preserved. (USFM validation tools may flag suspicious whitespace.)
.. _syntax_znamespace:
.. index:: marker (\z ...)
.. index:: marker; \z...
\\z namespace
-------------
@@ -116,7 +116,7 @@ As a means of offering a type of solution to the need for occasional local marku
However, it is much less likely that emerging digital publishing systems and work-flows will support user-generated/non-standardized project markup. Current procedures for interacting with these partner environments requires that translation data is delivered in rigidly validated formats which conform to specific agreed-upon interchange standards, such as the known USFM marker inventory, or some XML-based equivalents. Since connecting with these environments is much more exclusively software-driven than with many print production tools, encountering unknown markup within the publishing processes is a significant problem. Please consider this carefully before introducing non-standard USFM markup within a scripture translation project text.
.. _syntax_documentation:
.. index:: syntax (documentation)
.. index:: syntax; documentation
Documentation Syntax Notes
--------------------------
@@ -6,7 +6,7 @@ Chapters and Verses
===================
.. _usfmp_c:
.. index:: marker (\c)
.. index:: marker; \c, chapters; chapter number
\\c
^^^
@@ -39,7 +39,7 @@ Chapters and Verses
-----
.. _usfmc_ca:
.. index:: marker (\ca ...\ca*)
.. index:: marker; \ca ...\ca*, chapters; alternate chapter number
\\ca ...\\ca\*
^^^^^^^^^^^^^^
@@ -75,7 +75,7 @@ Chapters and Verses
-----
.. _usfmp_cl:
.. index:: marker (\cl)
.. index:: marker; \cl, chapters; chapter label
\\cl
^^^^
@@ -122,7 +122,7 @@ Psalm 1 (GNT - *markup adapted* - specific chapter label)
-----
.. _usfmp_cp:
.. index:: marker (\cp)
.. index:: marker; \cp, chapters; published chapter character
\\cp
^^^^
@@ -153,7 +153,7 @@ Psalm 1 (GNT - *markup adapted* - specific chapter label)
-----
.. _usfmp_cd:
.. index:: marker (\cd)
.. index:: marker; \cd; chapters; chapter description
\\cd
^^^^
@@ -185,7 +185,7 @@ Psalm 1 (GNT - *markup adapted* - specific chapter label)
-----
.. _usfmc_v:
.. index:: marker (\v)
.. index:: marker; \v, verses; verse number
\\v
^^^
@@ -217,7 +217,7 @@ Psalm 1 (GNT - *markup adapted* - specific chapter label)
-----
.. _usfmc_va:
.. index:: marker (\va ...\va*)
.. index:: marker; \va ...\va*, verses; alternate verse number
\\va ...\\va\*
^^^^^^^^^^^^^^
@@ -253,7 +253,7 @@ Psalm 1 (GNT - *markup adapted* - specific chapter label)
-----
.. _usfmc_vp:
.. index:: marker (\vp ...\vp*)
.. index:: marker; \vp ...\vp*, verses; published verse character
\\vp ...\\vp\*
^^^^^^^^^^^^^^
@@ -12,7 +12,7 @@ USFM 3.0 provides a general syntax for adding named attributes to character mark
USFM will *formally* provide descriptive attributes for a :ref:`subset <attributes_markersProviding>` of character markers. Each marker in this set will have a defined list of attributes, which are relevant to the overall purpose of the marker.
.. _attributes_syntax:
.. index:: attributes (syntax)
.. index:: attributes; syntax
General Syntax
^^^^^^^^^^^^^^
@@ -26,7 +26,7 @@ Within a character marker span, an attributes list is separated from the text co
\w gracious|lemma="grace"\w*
.. _attributes_default:
.. index:: attributes (default)
.. index:: attributes; default
Default Attribute
^^^^^^^^^^^^^^^^^
@@ -42,7 +42,7 @@ When content is supplied in the position of a marker attribute, but without an e
... where the default attribute for ``\w ...\w*`` is defined as being "lemma". This allows a commonly used attribute (the default) to be expressed with as little additional markup as possible within the text.
.. _attributes_multiValues:
.. index:: attributes (multiple values)
.. index:: attributes; multiple values
Multiple Attribute Values
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -58,15 +58,15 @@ In cases where more than one value should be provided for an attribute key, the
|ico_see| See the attributes for :ref:`\\w ...\\w\* <usfmc_w-attr>` for additional examples.
.. _attributes_backward:
.. index:: attributes (multiple values)
.. index:: attributes; backward compatibility
Backward Compatibility
^^^^^^^^^^^^^^^^^^^^^^
Any pre-existing markers which formally provide attributes in USFM 3.0 (or newer) may always continue to be used “un-decorated” (without attributes). ``\w gracious\w*`` remains valid USFM content.
.. _attributes_userDefined:
.. index:: attributes (multiple values)
.. index:: attributes; user-defined
User Defined Attributes
^^^^^^^^^^^^^^^^^^^^^^^
@@ -83,7 +83,7 @@ Any user defined attributes must begin with the prefix ``x-``.
\w gracious|lemma="grace" x-myattr="metadata"\w*
.. _attributes_markersProviding:
.. index:: attributes (markers providing)
.. index:: attributes; markers providing
Character Markers Providing Attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Oops, something went wrong.

0 comments on commit 59937af

Please sign in to comment.