Skip to content

Commit

Permalink
Update .. index:: texts to ensure that items are categorized well
Browse files Browse the repository at this point in the history
  • Loading branch information
@klassenjm
klassenjm committed Sep 9, 2016
1 parent 91a99df commit 59937af
Show file tree
Hide file tree
Showing 28 changed files with 231 additions and 224 deletions.
19 changes: 10 additions & 9 deletions docs/about/index.rst
View file
Original file line number Original file line Diff line number Diff line change
@@ -1,6 +1,7 @@
.. include:: /_static/inc_styles.txt .. include:: /_static/inc_styles.txt


.. index:: introduction, about, USFM (about) .. index:: introduction
pair: USFM; about


************ ************
Introduction Introduction
Expand All @@ -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. 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: .. _about_usfm_history:
.. index:: USFM (history) .. index:: pair: USFM; history


History of USFM History of USFM
--------------- ---------------
Expand All @@ -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. 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: .. _about_usfm_unification:
.. index:: USFM (unification notes) .. index:: USFM; unification notes


Unification Notes Unification Notes
----------------- -----------------
Expand All @@ -64,7 +65,7 @@ Unification Notes
* Marker definition "collisions" were resolved (same marker used to mark different content). * Marker definition "collisions" were resolved (same marker used to mark different content).


.. _about_usfm_software: .. _about_usfm_software:
.. index:: USFM (software notes) .. index:: USFM; software notes


Software Notes Software Notes
-------------- --------------
Expand All @@ -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. * 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: .. _about_usfm_changes:
.. index:: USFM (change management) .. index:: USFM; change management


Change Management Change Management
----------------- -----------------
Expand All @@ -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>`. |ico_See| See also: User extension :ref:`\\z namespace <syntax_znamespace>`.


.. _about_usfm_sty: .. _about_usfm_sty:
.. index:: stylesheets (ParaTExt) .. index:: pair: stylesheet; ParaTExt


ParaTExt Stylesheets ParaTExt Stylesheet
-------------------- -------------------
The most recent full and draft USFM stylesheet files for use with the ParaTExt translation editor are always available from http://paratext.org/usfm. The most recent full and draft USFM stylesheet file for use with the ParaTExt translation editor are always available from http://paratext.org/usfm.
16 changes: 8 additions & 8 deletions docs/about/syntax.rst
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Syntax Notes
----- -----


.. _syntax_general: .. _syntax_general:
.. index:: syntax (general) .. index:: syntax; general


General Syntax General Syntax
-------------- --------------
Expand All @@ -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*``. * 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: .. _syntax_numberedMarkers:
.. index:: syntax (numbered markers) .. index:: syntax; numbered markers


Numbered Markers Numbered Markers
---------------- ----------------
Expand All @@ -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.) 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: .. _syntax_endmarkerInNotes:
.. index:: syntax (endmarkers in notes) .. index:: syntax; endmarkers in notes


Endmarkers in Footnotes and Cross References Endmarkers in Footnotes and Cross References
-------------------------------------------- --------------------------------------------
Expand All @@ -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*`` B. ``\f + \fr 2.4\fr* \fk The \nd Lord\nd*:\fk* See \nd Lord\nd* in Word List.\f*``


.. _syntax_whitespace: .. _syntax_whitespace:
.. index:: syntax (whitespace) .. index:: syntax; whitespace, whitespace


Whitespace Whitespace
---------- ----------
Expand All @@ -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. - Multiple whitespace preceding a :doc:`paragraph </paragraphs/index>` marker.


.. _syntax_newline: .. _syntax_newline:
.. index:: syntax (newline) .. index:: syntax; newline, newlines


Newlines Newlines
^^^^^^^^ ^^^^^^^^
Expand All @@ -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. All paragraph markers should be preceded by a single newline.


.. _syntax_whitespace_normalization: .. _syntax_whitespace_normalization:
.. index:: syntax (whitespace) .. index:: pair: whitespace; normalization


Whitespace Normalization Whitespace Normalization
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -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.) * Normalized whitespace preceding the closing marker of a character or note marker pair is preserved. (USFM validation tools may flag suspicious whitespace.)


.. _syntax_znamespace: .. _syntax_znamespace:
.. index:: marker (\z ...) .. index:: marker; \z...


\\z namespace \\z namespace
------------- -------------
Expand All @@ -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. 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: .. _syntax_documentation:
.. index:: syntax (documentation) .. index:: syntax; documentation


Documentation Syntax Notes Documentation Syntax Notes
-------------------------- --------------------------
Expand Down
16 changes: 8 additions & 8 deletions docs/chapters_verses/index.rst
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Chapters and Verses
=================== ===================


.. _usfmp_c: .. _usfmp_c:
.. index:: marker (\c) .. index:: marker; \c, chapters; chapter number


\\c \\c
^^^ ^^^
Expand Down Expand Up @@ -39,7 +39,7 @@ Chapters and Verses
----- -----


.. _usfmc_ca: .. _usfmc_ca:
.. index:: marker (\ca ...\ca*) .. index:: marker; \ca ...\ca*, chapters; alternate chapter number


\\ca ...\\ca\* \\ca ...\\ca\*
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
Expand Down Expand Up @@ -75,7 +75,7 @@ Chapters and Verses
----- -----


.. _usfmp_cl: .. _usfmp_cl:
.. index:: marker (\cl) .. index:: marker; \cl, chapters; chapter label


\\cl \\cl
^^^^ ^^^^
Expand Down Expand Up @@ -122,7 +122,7 @@ Psalm 1 (GNT - *markup adapted* - specific chapter label)
----- -----


.. _usfmp_cp: .. _usfmp_cp:
.. index:: marker (\cp) .. index:: marker; \cp, chapters; published chapter character


\\cp \\cp
^^^^ ^^^^
Expand Down Expand Up @@ -153,7 +153,7 @@ Psalm 1 (GNT - *markup adapted* - specific chapter label)
----- -----


.. _usfmp_cd: .. _usfmp_cd:
.. index:: marker (\cd) .. index:: marker; \cd; chapters; chapter description


\\cd \\cd
^^^^ ^^^^
Expand Down Expand Up @@ -185,7 +185,7 @@ Psalm 1 (GNT - *markup adapted* - specific chapter label)
----- -----


.. _usfmc_v: .. _usfmc_v:
.. index:: marker (\v) .. index:: marker; \v, verses; verse number


\\v \\v
^^^ ^^^
Expand Down Expand Up @@ -217,7 +217,7 @@ Psalm 1 (GNT - *markup adapted* - specific chapter label)
----- -----


.. _usfmc_va: .. _usfmc_va:
.. index:: marker (\va ...\va*) .. index:: marker; \va ...\va*, verses; alternate verse number


\\va ...\\va\* \\va ...\\va\*
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
Expand Down Expand Up @@ -253,7 +253,7 @@ Psalm 1 (GNT - *markup adapted* - specific chapter label)
----- -----


.. _usfmc_vp: .. _usfmc_vp:
.. index:: marker (\vp ...\vp*) .. index:: marker; \vp ...\vp*, verses; published verse character


\\vp ...\\vp\* \\vp ...\\vp\*
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
Expand Down
12 changes: 6 additions & 6 deletions docs/characters/attributes.rst
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -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. 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: .. _attributes_syntax:
.. index:: attributes (syntax) .. index:: attributes; syntax


General Syntax General Syntax
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
Expand All @@ -26,7 +26,7 @@ Within a character marker span, an attributes list is separated from the text co
\w gracious|lemma="grace"\w* \w gracious|lemma="grace"\w*
.. _attributes_default: .. _attributes_default:
.. index:: attributes (default) .. index:: attributes; default


Default Attribute Default Attribute
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
Expand All @@ -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. ... 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: .. _attributes_multiValues:
.. index:: attributes (multiple values) .. index:: attributes; multiple values


Multiple Attribute Values Multiple Attribute Values
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -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. |ico_see| See the attributes for :ref:`\\w ...\\w\* <usfmc_w-attr>` for additional examples.


.. _attributes_backward: .. _attributes_backward:
.. index:: attributes (multiple values) .. index:: attributes; backward compatibility


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. 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: .. _attributes_userDefined:
.. index:: attributes (multiple values) .. index:: attributes; user-defined


User Defined Attributes User Defined Attributes
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -83,7 +83,7 @@ Any user defined attributes must begin with the prefix ``x-``.
\w gracious|lemma="grace" x-myattr="metadata"\w* \w gracious|lemma="grace" x-myattr="metadata"\w*
.. _attributes_markersProviding: .. _attributes_markersProviding:
.. index:: attributes (markers providing) .. index:: attributes; markers providing


Character Markers Providing Attributes Character Markers Providing Attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down
Loading

0 comments on commit 59937af

Please sign in to comment.