diff --git a/docs/container_types.rst b/docs/container_types.rst index e539ffa..776dc49 100644 --- a/docs/container_types.rst +++ b/docs/container_types.rst @@ -8,14 +8,32 @@ These different forms are represented by the following types. The types below are noted by ``Type Name (Type Slug)`` e.g. ``Book (book)`` -.. note:: Most types support a :ref:`condensed`. +.. note:: Most types support a condensed from. See :ref:`condensed` for details. .. _types-book: Book (book) ----------- -Represents any text that is structured like a book, there are chapters and chunks. +Represents any text that is structured like a book where there are chapters and chunks. + +Books of the Bible should use `usfm` for the file format. +Open Bible Stories should use `markdown` for the file format. + +.. code-block:: none + + content/ + ... + |-01/ + | |-title.md + | |-sub-title.md + | |-intro.md + | |-01.md + | |-02.md + | ... + | |-reference.md + | |-summary.md + ... Config ^^^^^^ @@ -30,18 +48,18 @@ The order of elements in each of these groups should be respected. 01: // chapter 01: // chunk dict: - - '//tw/bible/dict/creation' - - '//tw/bible/dict/god' - - '//tw/bible/dict/heaven' - - '//tw/bible/dict/holyspirit' + - 'rc://en/tw/bible/dict/creation' + - 'rc://en/tw/bible/dict/god' + - 'rc://en/tw/bible/dict/heaven' + - 'rc://en/tw/bible/dict/holyspirit' help: - - '//tq/gen/help/01/01' - - '//tn/gen/help/01/01' + - 'rc://en/tq/gen/help/01/01' + - 'rc://en/tn/gen/help/01/01' img: - - '//ulb/gen/img/01/01' + - 'rc://en/ulb/gen/img/01/01' .. note:: Implementation Notes: - References to external RCs may be displayed in the application along the side of the book content in order to provide contextual information. + References to supplementary RCs may be displayed in the application along the side of the book content in order to provide contextual information. .. _types-image: @@ -68,9 +86,6 @@ Below is an example with a format of ``image/png``. | |-02.png | ... ... - |-front/ - |-back/ - ... .. _types-audio: @@ -97,9 +112,6 @@ Below is an example with a format of ``audio/mp3``. | |-02.mp3 | ... ... - |-front/ - |-back/ - ... .. _types-video: @@ -126,17 +138,14 @@ Below is an example with a format of ``video/mp4``. | |-02.mp4 | ... ... - |-front/ - |-back/ - ... Help (help) ----------- -.. note:: These types do not support a :ref:`condensed`. +.. note:: This type does not support the :ref:`condensed form `. -A helpful resource to supplement chunks in a book. e.g. notes or questions. -Currently all help RCs must use the markdown format. +A helpful resource to supplement chunks in a book e.g. notes or questions, and is structured in the same was as a :ref:`types-book`. +All help RCs must use the markdown format. Each chunk contains one or more helps which correlate to the corresponding chunk in a book RC: @@ -159,28 +168,23 @@ If there is preceding text (without a header) it will be displayed as a single h Dictionary (dict) ----------------- -A standalone dictionary of terms. Currently all dictionary RCs must use the markdown format. +A standalone dictionary of terms. All dictionary RCs must use the markdown format. -The dictionary terms are used as the chapter :ref:`slug` and the description of the term is placed inside a ``01.txt`` file: +The dictionary terms are used as the chapter :ref:`identifier` and is most often organized in the :ref:`condensed form `. .. code-block:: none content/ - |-config.yaml - |-aaron/ - | |-01.txt - | - |-abel/ ... - |-unclean/ + |-aaron.md + |-abel.md + ... -.. note:: Lengthy dictionary terms may be split into more than one chunk. +.. note:: If desired, lengthy dictionary terms may use the :ref:`expanded form ` and be split into multiple chunks. The ``01.txt`` file contains the description of the term. The term title must always be at the top of the file as a h1 heading (a single #). :ref:`Links ` may be used to reference other words, or content in other containers. -.. note:: This type is in progress. We may add Strong's numbers to the markdown as well. - .. code-block:: markdown # Aaron # @@ -198,25 +202,25 @@ h1 heading (a single #). :ref:`Links ` may be used to reference other w * While the Israelites were traveling through the desert, Aaron sinned by making an idol for the people to worship. * God also appointed Aaron and his descendants to be the [priests](kt/priest) for the people of Israel. - (Translation suggestions: [How to Translate Names](en/ta-vol1/translate/man/translate-names)) + (Translation suggestions: [How to Translate Names](rc://en/ta-vol1/translate/man/translate-names)) - (See also: [[kt/priest]], [[other/moses]], [[other/israel]]) + (See also: [Priest](../kt/priest.md), [Moses](../other/moses.md), [Israel](../other/israel.md)) ## Bible References: ## - * [1 Chronicles 23:12-14](en/tn/1ch/help/23/12) - * [Acts 07:38-40](en/tn/act/help/07/38) - * [Exodus 28:1-3](en/tn/exo/help/28/01) - * [Luke 01:5-7](en/tn/luk/help/01/05) - * [Numbers 16:44-46](en/tn/num/help/16/44) + * [1 Chronicles 23:12-14](rc://en/tn/1ch/help/23/12) + * [Acts 07:38-40](rc://en/tn/act/help/07/38) + * [Exodus 28:1-3](rc://en/tn/exo/help/28/01) + * [Luke 01:5-7](rc://en/tn/luk/help/01/05) + * [Numbers 16:44-46](rc://en/tn/num/help/16/44) ## Examples from the Bible stories: ## - * __[09:15](en/tn/obs/help/09/15)__ God warned Moses and __Aaron__ that Pharaoh would be stubborn. - * __[10:05](en/tn/obs/help/10/05)__ Pharaoh called Moses and __Aaron__ and told them that if they stopped the plague, the Israelites could leave Egypt. - * __[13:09](en/tn/obs/help/13/09)__ God chose Moses' brother, __Aaron__, and Aaron's descendants to be his priests. - * __[13:11](en/tn/obs/help/13/11)__ So they (the Israelites) brought gold to __Aaron__ and asked him to form it into an idol for them! - * __[14:07](en/tn/obs/help/14/07)__ They (the Israelites) became angry with Moses and __Aaron__ and said, "Oh, why did you bring us to this horrible place?" + * __[09:15](rc://en/tn/obs/help/09/15)__ God warned Moses and __Aaron__ that Pharaoh would be stubborn. + * __[10:05](rc://en/tn/obs/help/10/05)__ Pharaoh called Moses and __Aaron__ and told them that if they stopped the plague, the Israelites could leave Egypt. + * __[13:09](rc://en/tn/obs/help/13/09)__ God chose Moses' brother, __Aaron__, and Aaron's descendants to be his priests. + * __[13:11](rc://en/tn/obs/help/13/11)__ So they (the Israelites) brought gold to __Aaron__ and asked him to form it into an idol for them! + * __[14:07](rc://en/tn/obs/help/14/07)__ They (the Israelites) became angry with Moses and __Aaron__ and said, "Oh, why did you bring us to this horrible place?" The ``config.yaml`` file contains extra details about the term that may be helpful for some automation tools. @@ -227,16 +231,16 @@ The ``config.yaml`` file contains extra details about the term that may be helpf aaron: false_positives: [] occurrences: - - 'en/ulb/1ch/book/23/12' - - 'en/ulb/1ch/book/07/38' - - 'en/ulb/1ch/book/28/01' - - 'en/ulb/1ch/book/01/05' - - 'en/ulb/1ch/book/16/44' - - 'en/obs/obs/book/09/15' - - 'en/obs/obs/book/10/05' - - 'en/obs/obs/book/13/09' - - 'en/obs/obs/book/13/11' - - 'en/obs/obs/book/14/07' + - 'rc://en/ulb/1ch/book/23/12' + - 'rc://en/ulb/1ch/book/07/38' + - 'rc://en/ulb/1ch/book/28/01' + - 'rc://en/ulb/1ch/book/01/05' + - 'rc://en/ulb/1ch/book/16/44' + - 'rc://en/obs/obs/book/09/15' + - 'rc://en/obs/obs/book/10/05' + - 'rc://en/obs/obs/book/13/09' + - 'rc://en/obs/obs/book/13/11' + - 'rc://en/obs/obs/book/14/07' Generally, ``false_positives`` and ``occurrences`` are mutually exclusive. That is, you should probably only have one or the other. @@ -254,9 +258,9 @@ If this key exists then a regex search should not be performed by the software. Manual (man) ------------ -A user manual. For now manual RCs must use the markdown format. +A user manual. All manuals must use the markdown format. -Manuals are a collection of modules (articles): +Manuals are a collection of modules/articles: .. code-block:: none @@ -271,7 +275,7 @@ Manuals are a collection of modules (articles): The ``01.txt`` file contains the translation of the module. -.. note:: If desired the module can be split into multiple chunks. +.. note:: If desired the module can be split into additional chunks. The ``config.yaml`` file indicates recommended and dependent modules: @@ -282,21 +286,21 @@ The ``config.yaml`` file indicates recommended and dependent modules: recommended: - 'translate-names' - 'translate-transliterate' - dependencies: + dependencies: - 'figs-sentences' -Dependencies are :ref:`slug` s of modules that should be read before this one. +Dependencies are :ref:`identifier` s of modules that should be read before this one. Recommendations are modules that would likely benefit the reader next. -.. _types-usfm: +.. _types-bundle: Bundle (bundle) --------------- -A bundle is simply a flat directory (no sub-folders) with a single file for each project. +A bundle is simply a flat directory (no sub-folders) with a single file for each project. e.g. there is no :ref:`structure-content`. This type is particularly suited for `USFM `_ when providing "USFM Bundles". -A project block in the :ref:`manifest`: +When defining a project in the :ref:`manifest` be sure the path is pointing to a file and not a directory. .. code-block:: yaml @@ -311,13 +315,13 @@ A project block in the :ref:`manifest`: categories: - 'bible-ot' -Directory structure +RC file structure: .. code-block:: none - myrc/ + my_rc/ + ... |-01-GEN.usfm - |-LICENSE.md |-manifest.yaml .. note:: When your application supports "USFM Bundles" it can identify the them in two ways diff --git a/docs/linking.rst b/docs/linking.rst index 3df7cd1..b6be946 100644 --- a/docs/linking.rst +++ b/docs/linking.rst @@ -4,130 +4,188 @@ Linking ======= A Resource Container (RC) link allows one RC to reference content from another RC. +Also, web links may be used to reference content online. -All RC links follow a very simple structure in two different flavors. +How links are written depends on the file format. +For example, a link within a markdown file would be displayed with the title in brackets and the url in parenthesis: -* **Anonymous links** - have no title and are declared by enclosing the link in double brackets -* **Titled links** - have a title and are indicated by enclosing the link title in single brackets and the link in parentheses. +.. code-block:: markdown -For example: + [Link Title](https://example.com) + +In markdown we support an additional link form that provides a link without a title. +The title in these cases will be automatically generated from the context: + +.. code-block:: markdown + + [[https://example.com]] + +RC links follow the same form as web links in that they have a `scheme` and `uri`. + +.. code-block:: markdown + + scheme://uri + +.. _linking-scheme: + +Scheme +------ + +RC links are identified by the ``rc`` schema in the same way that websites are identified by ``http``. +The scheme tells the software how to process the uri. .. code-block:: markdown - [[language/resource/project/type]] + rc://uri - [Link Title](language/resource/project/type) -Structure ---------- +URI +--- + +The uri in an RC link is composed, at minimum, of the following components. + +- **language** - an `IETF `_ compatible language tag indicating the language of the resource +- **resource** - an :ref:`identifier` for the resource +- **project** - an :ref:`identifier` for the project +- **type** - an :ref:`identifier` for the :ref:`Container Type ` + +Any additional information you include must be added after those mentioned above. + +.. code-block:: markdown + + rc://language/resource/project/type/extra/information + +.. _linking-glob: + +Wildcards +^^^^^^^^^ + +Some times it can be helpful to create a generic link. +Such as when referencing an entire resource like the English Unlocked Literal Bible. + +To facilitate this RC links support a wildcard ``*`` that can be used in place of any component in the :ref:`uri`. + +.. code-block:: markdown + + rc://en/ulb/*/book + +You can also do things like use a book in any available language + +.. code-block:: markdown + + rc://*/ulb/*/book + +.. _linking-resolution: + +Resolution +^^^^^^^^^^ + +An RC link is resolved like a file path. +The first few components address which RC to use. +And any remaining components address the specific content inside the RC. -The minimum form of a link is ``language/resource/project/type``. -We interpret this as the project content directory inside the RC. This is illustrated below: .. code-block:: none # link - en/ulb/gen/book + rc://en/ulb/exo/bundle - # file system - en_ulb_gen_book/ - |-LICENSE.md - |-manifest.yaml - |-content/ <-- link points here + # bundle RC on file system + en_ulb_bundle/ + ... + |-01-GEN.usfm + |-02-EXO.usfm <=== link points here + ... + +From this point we can lengthen the link to include a chapter :ref:`identifier`. -From this point we can lengthen the link to include a chapter :ref:`slug` which resolves to the chapter directory. +.. note:: If the RC is a :ref:`types-bundle` the client application is responsible for understanding + how to resolve to the chapter or any other location in the content. .. code-block:: markdown # link - en/ulb/gen/book/01 + rc://en/obs/obs/book/01 - # file system - en_ulb_gen_book/ - |-LICENSE.md - |-manifest.yaml + # book RC on file system + en_obs_obs_book/ + ... |-content/ - |-01/ <-- link points here + | |-01/ <=== link points here + | ... + ... Going a step further we can link to a specific chunk .. code-block:: none # link - en/ulb/gen/book/01/01 + rc://en/obs/obs/book/01/01 # file system - en_ulb_gen_book/ - |-LICENSE.md - |-manifest.yaml + en_obs_obs_book/ + ... |-content/ |-01/ - |-01.usfm <-- link points here + |-01.md <=== link points here In some of the examples above the link was not pointing directly at a file. In those cases the link should resolve to the first available file in order of the sorting priority described in :ref:`structure-content-sort`. - -External URLS -------------- - -You may link to online media by simply using a url instead of an RC identifier. - -- ``[[https://www.google.com]]`` -- ``[Google](https://www.google.com)`` - -Links where the path begins with ``http://`` or ``https://`` are treated as external urls. +.. note:: Depending on the client application, several files may be combined together when displayed to the user. + For example: when linking to a chapter in a book of the Bible it would make more sense to show at least the title + and summary, if not the rest of the chapter, rather than just the title. Examples --------- +^^^^^^^^ book ~~~~ -- ``[Genesis 1:2](en/ulb/gen/book/01/02)`` -- ``[Open Bible Stories 1:2](/en/obs/obs/book/01/02)`` +- ``[Genesis 1:2](rc://en/ulb/gen/book/01/02)`` +- ``[Open Bible Stories 1:2](rc://en/obs/obs/book/01/02)`` help ~~~~ -- ``[[en/tq/gen/help/01/02]]`` - links to translationQuestions for Genesis 1:2 -- ``[[en/tn/gen/help/01/02]]`` - links to translationNotes for Genesis 1:2 +- ``[[rc://en/tq/gen/help/01/02]]`` - links to translationQuestions for Genesis 1:2 +- ``[[rc://en/tn/gen/help/01/02]]`` - links to translationNotes for Genesis 1:2 dict ~~~~ -- ``[Canaan](en/tw/bible/dict/canaan)`` +- ``[Canaan](rc://en/tw/bible/dict/other/canaan)`` man ~~~ -- ``[Translate Unknowns](en/ta-vol1/translate/man/translate-unknowns)`` +- ``[Translate Unknowns](rc://en/ta/translate/man/translate-unknown)`` img ~~~ -- ``[Open Bible Stories 1:2](en/obs/obs/img/01/02)`` -- ``[Genesus 1:2-6](en/ulb/gen/img/01/02)`` +- ``[Open Bible Stories 1:2](rc://en/obs/obs/img/01/02)`` +- ``[Genesus 1:2-6](rc://en/ulb/gen/img/01/02)`` vid ~~~ -- ``[Open Bible Stories 1:2](en/obs/obs/vid/01/02)`` +- ``[Open Bible Stories 1:2](rc://en/obs/obs/vid/01/02)`` audio ~~~~~ -- ``[Open Bible Stories 1:2](en/obs/obs/audio/01/02)`` +- ``[Open Bible Stories 1:2](rc://en/obs/obs/audio/01/02)`` bundle ~~~~~~ -- ``[Genesis](en/ulb/gen/bundle/01/01)`` +- ``[Genesis](rc://en/ulb/gen/bundle/01/01)`` -.. note:: Linking to a bundle will only resolve down to the project level. e.g. the ``01/01`` will be ignored - and the entire project returned. - If you must link to a section within the project you will have to parse the content and +.. note:: Linking to a :ref:`types-bundle` will only resolve down to the project level. + e.g. the ``01/01`` in ``rc://en/ulb/gen/bundle/01/01`` will be ignored and the entire project returned. + If you must link to a section within the project your application will have to parse the content and manually resolve the rest of the link if the ``format`` supports references. Formats that support references are: @@ -135,6 +193,9 @@ bundle - usfm - osis +.. note:: When using RCs with multiple projects the application will need to inspect the :ref:`manifest` to determine + which :ref:`structure-content` to read while resolving a link. + .. _linking-abbreviations: Abbreviations @@ -143,41 +204,83 @@ Abbreviations In certain cases it is appropriate to abbreviate a link. Below are a list of cases where you are allowed to use an abbreviation. -Links within the same RC -~~~~~~~~~~~~~~~~~~~~~~~~ +.. _linking-internal: + +Internal Links +^^^^^^^^^^^^^^ + +When linking to a different section within the same RC +you may leave off the :ref:`linking-scheme` and simply provide a UNIX styled file path. +File extensions are optional. + +.. note:: you can use either an absolute path such as ``/my/path`` where ``/`` is the root directory of the RC + or relative path like ``../my/path``. -When linking to a different section within the same RC you may just provide the chapter/chunk :ref:`slug` s. +For example, let's say we have the following RC: -Manual example: +.. code-block:: none + + en-ta/ + ... + |-intro/ + | |-ta-intro/ + | | |-title.md + | | |-sub-title.md + | | |-01.md <====== link from here + | | + | ... + |-checking/ + | |-acceptable/ <====== to here + | | |-title.md + | | |-sub-title.md + | | |-01.md + | ... + ... + +With an internal link we can reference the "Acceptable Style" article +from within the "Introduction to translationAcademy" in any of the following ways: + +.. code-block:: none -- ``[Translate Unknowns](translate-unknowns)`` + [Acceptable Style](/checking/acceptable) + [Acceptable Style](../../checking/acceptable) -Dictionary example: +Notice some times it's more readable to use an absolute path instead of a relative path. -- ``[Canaan](canaan)`` +A better use case for relative paths would be in tW using the :ref:`condensed form `. -Book example: +.. code-block:: none -- ``[Genesis 1:2](01/02)`` + en-tw/ + ... + |-bible/ + | |-other/ + | | |-aaron.md + | | |-moses.md + | | ... + | ... + ... -Links to any language -~~~~~~~~~~~~~~~~~~~~~ +From within aaron.md we can link to moses in any of the following ways: -At times you may not wish to restrict the link to a particular language of the RC. -In that case you may exclude the language code from the beginning of the path and place an extra slash ``/`` in it's place. +.. code-block:: none -Example: + [Moses](moses) + [Moses](moses.md) + [Moses](./moses.md) + [Moses](../other/moses.md) + [Moses](/bible/other/moses.md) -- ``[[//ta-vol1/translate/man/translate-unknowns]]`` -- ``[Translate Unknowns](//ta-vol1/translate/man/translate-unknowns)`` +.. note:: For compatibility with displaying in online services such as github we suggest including the file extension + when practical and to use relative paths rather than absolute paths. .. _short-links: Short Links ------------ +^^^^^^^^^^^ A short link is used to reference a resource but not a project. -There is nothing fundamentally different from regular links. Short links are simply composed of just the language and resource. +Short links are composed of just the language and resource. - ``en/tn`` @@ -185,17 +288,17 @@ Short links are most often used within the :ref:`manifest` when referring to rel .. _linking-bible-refs: -Automatically Linking Bible References --------------------------------------- +Bible References +^^^^^^^^^^^^^^^^ -Bible references in any RC should be automatically converted into resolvable links according to the linking rules for **book** resource types. -Of course, if the reference is already a link nothing needs to be done. +Bible references in any RC may be automatically converted into resolvable links according to the linking rules for **book** resource types. +Of course, if the biblical reference is already a link nothing needs to be done. Conversion of biblical references are limited to those resources that have been indexed on the users' device. -Conversion should be performed based on any one of the following: +Conversion should be performed if in the text either of the following conditions is satisfied: -- a case *insensitive* match of the entire project title. -- a start case (first letter is uppercase) match of the project :ref:`slug` e.g. ``Gen``. +- a case *insensitive* match of the entire project title. e.g. ``Genesis`` is found in the text. +- a start case (first letter is uppercase) match of the project :ref:`identifier` e.g. ``Gen``. For each case above there must be a valid ``chapter:verse`` reference immediately after the matching word separated a single white space. For example: @@ -207,7 +310,7 @@ For example: Gen 1:1 Gen 1:1-3 -The chapter and verse numbers should be converted to properly formatted :ref:`slug` s. +The chapter and verse numbers should be converted to properly formatted :ref:`identifiers `. Example ~~~~~~~ @@ -217,20 +320,20 @@ Given the French reference below: ``Genèse 1:1`` If the user has only downloaded the English resource the link will not resolve because the title ``Genesis`` or ``genesis`` does not match ``Genèse`` or ``genèse``. -Neither does the camel case :ref:`slug` ``Gen`` match since it does not match the *entire* word. +Neither does the camel case :ref:`identifier` ``Gen`` match since it does not match the *entire* word. If the user now downloads the French resource the link will resolve because ``Genèse`` or ``genèse`` does indeed match ``Genèse`` or ``genèse``. The result will be: .. code-block:: markdown - [Genèse 1:1](fr/ulb/gen/book/01/01) + [Genèse 1:1](rc://fr/ulb/gen/book/01/01) Multiple Matches ~~~~~~~~~~~~~~~~ When a match occurs there may be several different resources that could be used in the link such as ``ulb`` or ``udb``. -When more than one resource :ref:`slug` is available use the following rules in order until a unique match is found: +When more than one resource :ref:`identifier` is available use the following rules in order until a unique match is found: 1. use the same resource as indicated by the application context. 2. use the RC allowed by the translate_mode set in the application. @@ -242,13 +345,13 @@ Aligning Verses to Chunks Because chunks may contain a range of verses, a passage reference may not exactly match up to a chunk. Therefore some interpolation may be nessesary. For both chapter and verse numbers perform the follow: - Given a chapter or verse number ``key``. - And an equivalent sorted list ``list`` of chapters or verses in the matched resource + Given a chapter or verse number **key**. + And an equivalent sorted list **list** of chapters or verses in the matched resource -- incrementally compare the key against items in the list. -- if the integer value of the current list item is less than the key: continue. -- if the integer value of the current list item is greater than the key: use the previous list item. -- if the end of the list is reached: use the previous list item. +- incrementally compare the **key** against items in the **list**. +- if the integer value of the current **list** item is less than the **key**: continue. +- if the integer value of the current **list** item is greater than the **key**: use the previous item in the **list**. +- if the end of the **list** is reached: use the previous item in the **list**. For example chunk ``01`` may contain verses ``1-3`` whereas chunk ``02`` contains verses ``4-6``. Therefore, verse ``2`` would resolve to chunk ``01``. diff --git a/docs/manifest.rst b/docs/manifest.rst index ff7d95b..a667a6d 100644 --- a/docs/manifest.rst +++ b/docs/manifest.rst @@ -12,7 +12,6 @@ and can be found nested within the ``dublin_core`` key. .. code-block:: yaml --- - dublin_core: conformsto: 'rc0.2' contributor: @@ -40,7 +39,7 @@ and can be found nested within the ``dublin_core`` key. identifier: 'asv' language: 'en' version: '1901' - subject: 'Bible translation' + subject: 'Bible' title: 'Unlocked Literal Bible' type: 'book' version: '3' @@ -68,24 +67,29 @@ Definitions - ``dublin_core`` - - ``conformsto``: the version of the RC specification used by the RC. - - ``contributor``: an array of names or aliases to people that have contributed to the resource. - - ``format``: the file format of content within the RC, e.g. - - - ``text/usfm`` - - ``image/png`` - - ``audio/mp3`` - - - ``identifier``: a :ref:`slug` formatted string uniquely identifying the resource. + - ``conformsto``: the version of this specification used by the RC. + - ``contributor``: an array of names or aliases of people that have contributed to the resource. + - ``creator``: the entity in charge of creating the resource. + - ``description``: a brief description of what the resource is. + - ``format``: the file format of content within the RC, e.g. ``text/usfm``, ``text/markdown`` etc. + - ``identifier``: a :ref:`identifier` formatted string uniquely identifying the resource. - ``issued``: the :ref:`date` of publication. - - ``publisher``: the name of the individual or organization responsible for publishing the resource. + - ``language``: the language of the resource. + - ``modified``: the date the resource was last modified. + - ``publisher``: the name of the entity that published the resource. - ``relation``: a array of :ref:`short-links` to related resources. - - ``type``: the RC type. + - ``rights``: the license under which the resource is distributed. + - ``title``: the title of the resource + - ``type``: the RC :ref:`container type `. + - ``version``: the published iteration of the resource. - ``projects``: an array of projects inside the RC. - - ``identifier``: a :ref:`slug` formatted string uniquely identifying the project. + - ``categories``: an array of category :ref:`identifiers ` used for hierarchical ordering. + - ``identifier``: an :ref:`identifier` formatted string uniquely identifying the project. - ``path``: the relative path to the project within the RC. Depending on the RC type this may be a directory or a file. + - ``sort``: the sorting order of this project when viewed in relation to other projects in this RC. + - ``title``: the title of the project. - ``versification``: the system used for placing verse markers and consequently chunk markers. Generating From USFM diff --git a/docs/slug.rst b/docs/slug.rst index 8e8a31c..429fb64 100644 --- a/docs/slug.rst +++ b/docs/slug.rst @@ -1,22 +1,22 @@ -.. _slug: +.. _identifier: -Slug -==== +Identifier +========== -A slug is a word or a few words that uniquely describe an object. -Slugs are often used instead of an id (from a database) due to their readability and portability. +An identifier is a word or a few words that uniquely describe an object. +Identifiers are often used instead of a database id due to their readability and portability. Syntax ------ -Slugs are composed of lowercase alphanumeric characters and hyphens. +Identifiers are composed of lowercase alphanumeric characters and hyphens. .. code-block:: none abcdefghijklmnopqrstuvwxyz1234567890- -* The first character in a slug *must* be a letter. -* The last character in a slug *must not* be a hyphen. +* The first character in an identifier *must* be a letter. +* The last character in an identifier *must not* be a hyphen. Examples -------- @@ -26,5 +26,5 @@ Examples gen pt-br aey-x-haya - custom-slug-123 - my-1st-slug \ No newline at end of file + custom-identifier-123 + my-1st-identifier \ No newline at end of file diff --git a/docs/structure.rst b/docs/structure.rst index b56535f..db291ee 100644 --- a/docs/structure.rst +++ b/docs/structure.rst @@ -1,4 +1,5 @@ .. _structure: + Resource Container Structure ============================ @@ -13,10 +14,11 @@ A git repository is also a valid way to store RCs. .. note:: When naming an RC directory or repository the best practice is to use a combination of the resource and project identifiers e.g. ``en-ulb-gen``. - If the RC contains more than one project just use the resource identifier with an optional :ref:`slug` formatted qualifier + If the RC contains more than one project just use the resource identifier with an optional :ref:`identifier` formatted qualifier e.g. ``en-ulb-nt`` where ``nt`` is the custom qualifier denoting the New Testament. .. _structure-directory: + Directory Structure ------------------- @@ -31,20 +33,20 @@ RCs have a folder structure like the following: |-manifest.yaml |-content/ -- ``.git``: only exists when the RC is stored in a git repository. +- ``.git``: only exists when the RC is stored as a git repository. - ``.apps``: is where applications can store custom meta data about the RC. See :doc:`app_meta` for more information. - ``LICENSE.md``: contains the appropriate license information for the RC. - ``manifest.yaml``: is the RC :ref:`manifest`. - ``content``: contains the project files. The name of this directory is subject to the :ref:`manifest`. - It is also possible for there to be multiple directories or excluded altogether. + It is also possible for there to be multiple :ref:`Projects Directories ` or be excluded altogether. .. _structure-content: Project Directory ----------------- -The folder structure of the project directory in RCs is mostly the same across RC types. -The most common structure is indicated below: +The project directory is where all of the translation information exists for a single project within an RC. +Files in this directory may contain either meta data or readable text. .. code-block:: none @@ -52,59 +54,95 @@ The most common structure is indicated below: |-config.yaml |-toc.yaml |-front/ - |-01/ - | |-title.txt - | |-sub-title.txt - | |-intro.txt - | |-01.txt - | |-02.txt - | ... - | |-reference.txt - | |-summary.txt - ... |-back/ -.. note:: Where a .txt extension is shown above, the proper extension should be used according to the format - indicated in the :ref:`manifest`. For example ``.usfm`` or ``.md``. +The folders and files illustrated above are reserved. +Although not required, when used they must fulfill their roles as defined: + +- ``config.yaml`` contains meta data for the project at varying levels of granularity as specified in the :ref:`types`. +- ``toc.yaml`` contains the :ref:`structure-toc`. +- ``front`` directory contains the front matter. +- ``back`` directory contains the back matter. + +Furthermore, there are reserved chunk files which may exist in any folder +including the reserved `front` and `back` folders: + +.. note:: we use ``md`` for the file extension in this example. + You should use a file extension that is appropriate for content in your :ref:`Container Type `. + +.. code-block:: none + + content/ + ... + |-front/ + | |-title.md + | |-sub-title.md + | |-intro.md + | |-reference.md + | |-summary.md + ... + +Once again, these files are not required but must fulfill their roles as defined: -The directories within ``content`` shown above indicate chapters. -There are two special chapters named ``front`` and ``back`` that contain, if applicable, the front and back matter. +**when in a chapter** -The files within each chapter represent the chunks of the chapter. -Often the chunk file names will be numeric (e.g. ``01.txt``) but that is not required. -The following reserved chunk names have special meaning: +- ``title.md`` - contains the chapter title +- ``sub-title.md`` - contains the sub title of the chapter +- ``intro.md`` - contains the introduction to the chapter +- ``reference.md`` - contains a reference displayed at the end of a chapter +- ``summary.md`` - contains a summary displayed at the end of a chapter -- ``title.txt`` - the title of the chapter -- ``sub-title.txt`` - the sub title of the chapter -- ``intro.txt`` - the introduction to the chapter -- ``reference.txt`` - a reference displayed at the end of a chapter -- ``summary.txt`` - a summary displayed at the end of a chapter +**when in "front"** -In the case of front and back matter, the above named chunks apply to the project, such as the project title, project summary, etc. +- ``title.md`` - contains the resource title +- ``sub-title.md`` - contains the sub title of the resource +- ``intro.md`` - contains the introduction to the resource +- ``reference.md`` - contains a reference displayed at the end of the front matter +- ``summary.md`` - contains a summary displayed at the end of the front matter .. _condensed: -Condensed Form -^^^^^^^^^^^^^^ +Condensed vs Expanded Form +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +At times content can be structured slightly differently for added convenience. +If the :ref:`container type ` supports it an RC may use one form or the other or both simultaneously. -.. note:: This specification makes no distinction between condensed and :ref:`expanded ` forms. This is simply shown as an - alternative style. Client applications should be prepared to support your chosen style. +**Expanded** -Most :ref:`types` support a condensed form in which content in each folder is stored -in a single file. e.g. +All :ref:`types` support the expanded form. +This form is most suitable for active translations because collaborators are less likely to interfere with other's files. +And it decouples formatting from structure. +For example, here's a :ref:`structure-content` that has a chapter 1 folder containing several chunks: .. code-block:: none content/ - |-config.yaml - |-toc.yaml - |-front/ + ... |-01/ - | |-01.txt + | |-title.md + | |-01.md + | ... + | |-reference.md + |-02/ ... - |-back/ -Where the file ``01.txt`` may contain the title, sub-title, intro, chunks etc. + +**Condensed** + +Most :ref:`types` support a condensed form in which content in each chapter folder is stored +in a single file. +this form is most suitable for content being delivered as source text: + +.. code-block:: none + + content/ + ... + |-01.md + |-02.md + ... + +Where the file ``01.md`` may contain the title, sub-title, intro, chunks, etc. for chapter 1. .. _structure-content-sort: @@ -132,21 +170,20 @@ The content sorting rules are defined as: 7. summary .. _structure-config: + Config ------ The ``config.yaml`` file contains information specific to each :ref:`RC type `. If a particular :ref:`RC type ` does not need this file it may be excluded. .. _structure-toc: + Table of Contents ----------------- -.. include:: includes/note_keys_required.txt - Chapter directories and chunk files are often named with padded integers. A side effect of this is the natural file order often represents the appropriate order. -However, you may also indicate the order of chapters and frames by providing a table of contents, ``toc.yaml``, within the content directory. -If no such file exists then the integer order followed by the natural order of the files will be used. +However, you may also indicate the order of chapters and frames by providing a table of contents, ``toc.yaml``, within the :ref:`structure-content`. The table of contents is built with small blocks as shown below. All of the fields in the blocks are optional: @@ -158,8 +195,10 @@ The table of contents is built with small blocks as shown below. All of the fiel link: "my-link" sections: [] -The sections field allows you to nest more blocks. The link fields may accept the chunk that should be linked to. -Alternatively, you may provide a fully qualified link as defined in :ref:`linking`. +- ``title`` a header in the table of contents +- ``sub-title`` a sub heading in the table of contents +- ``sections`` allow you to nest more blocks. +- ``link`` is the chapter :ref:`identifier` that should be linked to. Alternatively, you may provide a fully qualified link as defined in :ref:`linking`. Here is an example ``toc.yaml`` from `translationAcademy `_. Generally speaking the title and sub-title fields in this file should be the same as what is found in the subsequently named chunks. @@ -168,115 +207,44 @@ However, the TOC is allowed to deviate as necessary. .. code-block:: yaml --- - title: "translationAcademy Table of Contents" - sub-title: "" - link: "" - sections: - - - title: "Introduction to translationAcademy" - sub-title: "This page answers the question: What is in the Introduction?" - link: "" - sections: - - - title: "Introduction" - sub-title: "" - link: "" - sections: - - - title: "" - sub-title: "" - link: "ta-intro" - sections: [] - - - title: "" - sub-title: "" - link: "uw-intro" - sections: [] - - - title: "Table Of Contents - Process Manual Vol 1" - sub-title: "This page answers the question: What is in the process manual volume 1?" - sections: - - - title: "Process Manual Volume 1" - sub-title: "" - link: "" - sections: - - - title: "1. Getting Started" - sub-title: "" - link: "" - sections: - - - title: "" - sub-title: "" - link: "process-manual" - sections: [] - - - title: "" - sub-title: "" - link: "getting-started" - sections: [] - - - title: "2. Setting Up a Translation Team" - sub-title: "" - link: "" - sections: - - - title: "" - sub-title: "" - link: "setup-team" - sections: [] - - - title: "Table Of Contents - Translation Manual Volume 1" - sub-title: "This page answers the question: What is in Volume 1 of the translation manual?" - sections: [] - -Alternatively you can choose to use a simplified table of contents as shown below. - -.. note:: We may deprecate this form due to the addition of content sorting instructions describe above. - Since sorting is defined this form may not provide anything useful. - -.. code-block:: yaml - - --- - - - chapter: '01' - chunks: - - title - - '01' - - '02' - - '03' - - '04' - - '05' - - '06' - - '07' - - '08' - - '09' - - '10' - - '11' - - '12' - - '13' - - '14' - - '15' - - '16' - - reference - - - chapter: '02' - chunks: - - title - - '01' - - '02' - - '03' - - '04' - - '05' - - '06' - - '07' - - '08' - - '09' - - '10' - - '11' - - '12' - - reference - -The simple version will rely on the available content (titles, references, etc.) to generate the table of contents -(readable titles will be retrieved from the content itself). + title: "Table of Contents" + sections: + - title: "1. Getting Started" + sections: + - title: "Introduction to the Process Manual" + link: process-manual + + - title: "2. Setting Up a Translation Team" + sections: + - title: "Setting Up A Translation Team" + link: setup-team + + - title: "3. Translating" + sections: + - title: "Training Before Translation Begins" + link: pretranslation-training + - title: "Choosing a Translation Platform" + link: platforms + - title: "Setting Up translationStudio" + link: setup-ts + + - title: "4. Checking" + sections: + - title: "Training Before Checking Begins" + link: prechecking-training + - title: "How to Check" + link: required-checking + + - title: "5. Publishing" + sections: + - title: "Introduction to Publishing" + link: intro-publishing + - title: "Source Text Process" + link: source-text-process + + - title: "6. Distributing" + sections: + - title: "Introduction to Distribution" + link: intro-share + - title: "How to Share Content" + link: share-content