From b225b8fe12ee8df179f770f4ae2f1e99bb02696e Mon Sep 17 00:00:00 2001 From: Joel Lonbeck Date: Thu, 4 May 2017 13:10:52 -0700 Subject: [PATCH 1/9] updated project structure, and condensed vs expanded --- docs/container_types.rst | 24 ++++++++- docs/structure.rst | 108 ++++++++++++++++++++++++++------------- 2 files changed, 94 insertions(+), 38 deletions(-) diff --git a/docs/container_types.rst b/docs/container_types.rst index e539ffa..d5c87dd 100644 --- a/docs/container_types.rst +++ b/docs/container_types.rst @@ -8,7 +8,7 @@ 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: @@ -16,6 +16,26 @@ Book (book) ----------- Represents any text that is structured like a book, there are chapters and chunks. +Books RCs should use `usfm` for the file format if the Bible or `markdown` if OBS. + +.. code-block:: none + + content/ + |-config.yaml + |-toc.yaml + |-front/ + |-01/ + | |-title.txt + | |-sub-title.txt + | |-intro.txt + | |-01.txt + | |-02.txt + | ... + | |-reference.txt + | |-summary.txt + ... + |-back/ + ... Config ^^^^^^ @@ -133,7 +153,7 @@ Below is an example with a format of ``video/mp4``. 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. diff --git a/docs/structure.rst b/docs/structure.rst index b56535f..7328a8d 100644 --- a/docs/structure.rst +++ b/docs/structure.rst @@ -1,4 +1,5 @@ .. _structure: + Resource Container Structure ============================ @@ -17,6 +18,7 @@ A git repository is also a valid way to store RCs. e.g. ``en-ulb-nt`` where ``nt`` is the custom qualifier denoting the New Testament. .. _structure-directory: + Directory Structure ------------------- @@ -36,15 +38,15 @@ RCs have a folder structure like the following: - ``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,91 @@ 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: -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. +- ``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. -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: +Furthermore, there are reserved chunk files which may exist in any folder +including the reserved `front` and `back` folders: -- ``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 +.. note:: we use ``ext`` to indicate a wildcard file extension. + You should use a file extension that is appropriate for content in your :ref:`Container Type `. -In the case of front and back matter, the above named chunks apply to the project, such as the project title, project summary, etc. +.. code-block:: none + + content/ + ... + |-front/ + | |-title.ext + | |-sub-title.ext + | |-intro.ext + | |-reference.ext + | |-summary.ext + ... + +Once again, these files are not required but must fulfill their roles as defined: + +**when in a chapter** + +- ``title.txt`` - contains the chapter title +- ``sub-title.txt`` - contains the sub title of the chapter +- ``intro.txt`` - contains the introduction to the chapter +- ``reference.txt`` - contains a reference displayed at the end of a chapter +- ``summary.txt`` - contains a summary displayed at the end of a chapter + +**when in "front"** + +- ``title.txt`` - contains the resource title +- ``sub-title.txt`` - contains the sub title of the resource +- ``intro.txt`` - contains the introduction to the resource +- ``reference.txt`` - contains a reference displayed at the end of the front matter +- ``summary.txt`` - contains a summary displayed at the end of the front matter .. _condensed: -Condensed Form -^^^^^^^^^^^^^^ +Condensed vs Expanded Form +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Although not officially part of this specification, we offer two suggested forms for storing content. -.. 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** + +All :ref:`types` support the expanded form. +For example, here's :ref:`structure-content` that has a chapter 1 folder containing several chunks: + +.. code-block:: none + + content/ + ... + |-01/ + | |-title.md + | |-01.md + | ... + | |-reference.txt + ... + + +**Condensed** Most :ref:`types` support a condensed form in which content in each folder is stored -in a single file. e.g. +in a single file: .. code-block:: none content/ - |-config.yaml - |-toc.yaml - |-front/ + ... |-01/ | |-01.txt ... - |-back/ -Where the file ``01.txt`` may contain the title, sub-title, intro, chunks etc. +Where the file ``01.txt`` may contain the title, sub-title, intro, chunks etc. formatted appropriately so it can +be read by a client application. .. _structure-content-sort: @@ -132,12 +166,14 @@ 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 ----------------- From a7f862edf980b2f20a780e41fa9fed42cd9d4422 Mon Sep 17 00:00:00 2001 From: Joel Lonbeck Date: Thu, 4 May 2017 13:11:54 -0700 Subject: [PATCH 2/9] removed simple table of contents --- docs/structure.rst | 50 ---------------------------------------------- 1 file changed, 50 deletions(-) diff --git a/docs/structure.rst b/docs/structure.rst index 7328a8d..bdd1ba5 100644 --- a/docs/structure.rst +++ b/docs/structure.rst @@ -266,53 +266,3 @@ However, the TOC is allowed to deviate as necessary. 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). From f46d30f09845d57076a064096db021af25a1fbca Mon Sep 17 00:00:00 2001 From: Joel Lonbeck Date: Thu, 4 May 2017 17:21:01 -0700 Subject: [PATCH 3/9] fixes #44 part of #43 and #38 --- docs/container_types.rst | 6 +- docs/linking.rst | 251 +++++++++++++++++++++++++++------------ docs/manifest.rst | 4 +- docs/slug.rst | 20 ++-- docs/structure.rst | 43 +++---- 5 files changed, 213 insertions(+), 111 deletions(-) diff --git a/docs/container_types.rst b/docs/container_types.rst index d5c87dd..8b88911 100644 --- a/docs/container_types.rst +++ b/docs/container_types.rst @@ -181,7 +181,7 @@ Dictionary (dict) A standalone dictionary of terms. Currently 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 the description of the term is placed inside a ``01.txt`` file: .. code-block:: none @@ -305,10 +305,10 @@ The ``config.yaml`` file indicates recommended and dependent modules: 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) --------------- diff --git a/docs/linking.rst b/docs/linking.rst index 3df7cd1..a64c461 100644 --- a/docs/linking.rst +++ b/docs/linking.rst @@ -4,128 +4,186 @@ 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 would 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 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 +.. note:: Linking to a :ref:`types-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 manually resolve the rest of the link if the ``format`` supports references. @@ -135,6 +193,9 @@ bundle - usfm - osis +.. note:: When using RCs with multiple projects you'll need to reference the :ref:`manifest` to determine + which :ref:`structure-content` to use. + .. _linking-abbreviations: Abbreviations @@ -143,38 +204,78 @@ 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 give the file path within the RC using UNIX styled file paths. + +.. note:: you can use either an absolute path such as ``/my/path`` where ``/`` is the root directory of the RC + or relative paths 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 `. +This is is a made up example. -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) -- ``[[//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. .. _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. @@ -185,8 +286,8 @@ 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. @@ -195,7 +296,7 @@ Conversion of biblical references are limited to those resources that have been Conversion should be performed based on any one of the following: - 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 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 +308,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 +318,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. diff --git a/docs/manifest.rst b/docs/manifest.rst index ff7d95b..e4365df 100644 --- a/docs/manifest.rst +++ b/docs/manifest.rst @@ -76,7 +76,7 @@ Definitions - ``image/png`` - ``audio/mp3`` - - ``identifier``: a :ref:`slug` formatted string uniquely identifying the resource. + - ``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. - ``relation``: a array of :ref:`short-links` to related resources. @@ -84,7 +84,7 @@ Definitions - ``projects``: an array of projects inside the RC. - - ``identifier``: a :ref:`slug` formatted string uniquely identifying the project. + - ``identifier``: a :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. - ``versification``: the system used for placing verse markers and consequently chunk markers. 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 bdd1ba5..0a3dee2 100644 --- a/docs/structure.rst +++ b/docs/structure.rst @@ -14,7 +14,7 @@ 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: @@ -67,7 +67,7 @@ Although not required, when used they must fulfill their roles as defined: Furthermore, there are reserved chunk files which may exist in any folder including the reserved `front` and `back` folders: -.. note:: we use ``ext`` to indicate a wildcard file extension. +.. 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 @@ -75,30 +75,30 @@ including the reserved `front` and `back` folders: content/ ... |-front/ - | |-title.ext - | |-sub-title.ext - | |-intro.ext - | |-reference.ext - | |-summary.ext + | |-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: **when in a chapter** -- ``title.txt`` - contains the chapter title -- ``sub-title.txt`` - contains the sub title of the chapter -- ``intro.txt`` - contains the introduction to the chapter -- ``reference.txt`` - contains a reference displayed at the end of a chapter -- ``summary.txt`` - contains a summary displayed at the end of a chapter +- ``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 **when in "front"** -- ``title.txt`` - contains the resource title -- ``sub-title.txt`` - contains the sub title of the resource -- ``intro.txt`` - contains the introduction to the resource -- ``reference.txt`` - contains a reference displayed at the end of the front matter -- ``summary.txt`` - contains a summary displayed at the end of the front matter +- ``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: @@ -120,7 +120,8 @@ For example, here's :ref:`structure-content` that has a chapter 1 folder contain | |-title.md | |-01.md | ... - | |-reference.txt + | |-reference.md + |-02/ ... @@ -133,11 +134,11 @@ in a single file: content/ ... - |-01/ - | |-01.txt + |-01.md + |-02.md ... -Where the file ``01.txt`` may contain the title, sub-title, intro, chunks etc. formatted appropriately so it can +Where the file ``01.md`` may contain the title, sub-title, intro, chunks etc. formatted appropriately so it can be read by a client application. .. _structure-content-sort: From 202751742e5b41e59ecf3d6818db8518dc5b0790 Mon Sep 17 00:00:00 2001 From: Joel Lonbeck Date: Fri, 5 May 2017 10:17:44 -0700 Subject: [PATCH 4/9] updated notes --- docs/linking.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/linking.rst b/docs/linking.rst index a64c461..7ae3d12 100644 --- a/docs/linking.rst +++ b/docs/linking.rst @@ -270,7 +270,7 @@ From within aaron.md we can link to moses in any of the following ways: [Moses](./moses.md) .. note:: For compatibility with displaying in online services such as github we suggest including the file extension - when practical. + when practical and to use relative paths rather than absolute paths. .. _short-links: From cf49e3d540e59a63226388d5147f45e6ad6ddb05 Mon Sep 17 00:00:00 2001 From: Joel Lonbeck Date: Fri, 5 May 2017 16:37:02 -0700 Subject: [PATCH 5/9] tweaks, updating toc docs --- docs/structure.rst | 125 +++++++++++++++++++-------------------------- 1 file changed, 53 insertions(+), 72 deletions(-) diff --git a/docs/structure.rst b/docs/structure.rst index 0a3dee2..9d0fc12 100644 --- a/docs/structure.rst +++ b/docs/structure.rst @@ -33,7 +33,7 @@ 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`. @@ -105,12 +105,14 @@ Once again, these files are not required but must fulfill their roles as defined Condensed vs Expanded Form ^^^^^^^^^^^^^^^^^^^^^^^^^^ -Although not officially part of this specification, we offer two suggested forms for storing content. +We offer two suggested forms for storing content. **Expanded** All :ref:`types` support the expanded form. -For example, here's :ref:`structure-content` that has a chapter 1 folder containing several chunks: +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 @@ -128,7 +130,8 @@ For example, here's :ref:`structure-content` that has a chapter 1 folder contain **Condensed** Most :ref:`types` support a condensed form in which content in each folder is stored -in a single file: +in a single file. +this form is most suitable for content being delivered as source text: .. code-block:: none @@ -178,12 +181,9 @@ The ``config.yaml`` file contains information specific to each :ref:`RC type `_. Generally speaking the title and sub-title fields in this file should be the same as what is found in the subsequently named chunks. @@ -205,65 +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: [] + 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 From ceb1428e33a03820e997db2623bb5626e0d60593 Mon Sep 17 00:00:00 2001 From: Joel Lonbeck Date: Fri, 5 May 2017 16:51:58 -0700 Subject: [PATCH 6/9] improvements to manifest docs --- docs/manifest.rst | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/docs/manifest.rst b/docs/manifest.rst index e4365df..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`` - + - ``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:`identifier` 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 From c75e2d1a7019d965d7ec436c2452518267e58504 Mon Sep 17 00:00:00 2001 From: Joel Lonbeck Date: Fri, 5 May 2017 17:21:43 -0700 Subject: [PATCH 7/9] improvements to container types docs --- docs/container_types.rst | 134 +++++++++++++++++---------------------- docs/structure.rst | 3 +- 2 files changed, 61 insertions(+), 76 deletions(-) diff --git a/docs/container_types.rst b/docs/container_types.rst index 8b88911..776dc49 100644 --- a/docs/container_types.rst +++ b/docs/container_types.rst @@ -15,26 +15,24 @@ The types below are noted by ``Type Name (Type Slug)`` e.g. ``Book (book)`` Book (book) ----------- -Represents any text that is structured like a book, there are chapters and chunks. -Books RCs should use `usfm` for the file format if the Bible or `markdown` if OBS. +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/ - |-config.yaml - |-toc.yaml - |-front/ + ... |-01/ - | |-title.txt - | |-sub-title.txt - | |-intro.txt - | |-01.txt - | |-02.txt + | |-title.md + | |-sub-title.md + | |-intro.md + | |-01.md + | |-02.md | ... - | |-reference.txt - | |-summary.txt - ... - |-back/ + | |-reference.md + | |-summary.md ... Config @@ -50,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: @@ -88,9 +86,6 @@ Below is an example with a format of ``image/png``. | |-02.png | ... ... - |-front/ - |-back/ - ... .. _types-audio: @@ -117,9 +112,6 @@ Below is an example with a format of ``audio/mp3``. | |-02.mp3 | ... ... - |-front/ - |-back/ - ... .. _types-video: @@ -146,17 +138,14 @@ Below is an example with a format of ``video/mp4``. | |-02.mp4 | ... ... - |-front/ - |-back/ - ... Help (help) ----------- .. 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: @@ -179,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:`identifier` 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 # @@ -218,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. @@ -247,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. @@ -274,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 @@ -291,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: @@ -302,7 +286,7 @@ The ``config.yaml`` file indicates recommended and dependent modules: recommended: - 'translate-names' - 'translate-transliterate' - dependencies: + dependencies: - 'figs-sentences' Dependencies are :ref:`identifier` s of modules that should be read before this one. @@ -313,10 +297,10 @@ Recommendations are modules that would likely benefit the reader next. 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 @@ -331,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/structure.rst b/docs/structure.rst index 9d0fc12..bf2052e 100644 --- a/docs/structure.rst +++ b/docs/structure.rst @@ -105,7 +105,8 @@ Once again, these files are not required but must fulfill their roles as defined Condensed vs Expanded Form ^^^^^^^^^^^^^^^^^^^^^^^^^^ -We offer two suggested forms for storing content. +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. **Expanded** From 402552cdaaafb1d53177728d8fee61e5ba8a25d2 Mon Sep 17 00:00:00 2001 From: Joel Lonbeck Date: Fri, 5 May 2017 17:48:15 -0700 Subject: [PATCH 8/9] updates to linking --- docs/linking.rst | 48 +++++++++++++++++++++++++----------------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/docs/linking.rst b/docs/linking.rst index 7ae3d12..b6be946 100644 --- a/docs/linking.rst +++ b/docs/linking.rst @@ -14,7 +14,7 @@ For example, a link within a markdown file would be displayed with the title in [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 would be automatically generated from the context: +The title in these cases will be automatically generated from the context: .. code-block:: markdown @@ -134,8 +134,8 @@ 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`. .. note:: Depending on the client application, several files may be combined together when displayed to the user. - For example: when linking to 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. + 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 ^^^^^^^^ @@ -183,9 +183,9 @@ bundle - ``[Genesis](rc://en/ulb/gen/bundle/01/01)`` -.. note:: Linking to a :ref:`types-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: @@ -193,8 +193,8 @@ bundle - usfm - osis -.. note:: When using RCs with multiple projects you'll need to reference the :ref:`manifest` to determine - which :ref:`structure-content` to use. +.. 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: @@ -210,10 +210,11 @@ Internal Links ^^^^^^^^^^^^^^ When linking to a different section within the same RC -you may leave off the :ref:`linking-scheme` and simply give the file path within the RC using UNIX styled file paths. +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 paths like ``../my/path``. + or relative path like ``../my/path``. For example, let's say we have the following RC: @@ -237,7 +238,7 @@ For example, let's say we have the following RC: ... With an internal link we can reference the "Acceptable Style" article -from within the introduction to translationAcademy in any of the following ways: +from within the "Introduction to translationAcademy" in any of the following ways: .. code-block:: none @@ -247,7 +248,6 @@ from within the introduction to translationAcademy in any of the following ways: Notice some times it's more readable to use an absolute path instead of a relative path. A better use case for relative paths would be in tW using the :ref:`condensed form `. -This is is a made up example. .. code-block:: none @@ -268,6 +268,8 @@ From within aaron.md we can link to moses in any of the following ways: [Moses](moses) [Moses](moses.md) [Moses](./moses.md) + [Moses](../other/moses.md) + [Moses](/bible/other/moses.md) .. 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. @@ -278,7 +280,7 @@ 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`` @@ -289,13 +291,13 @@ Short links are most often used within the :ref:`manifest` when referring to rel 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 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. @@ -343,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``. From 49e79b15172fdc721f54aa0526ce3a886918d6f8 Mon Sep 17 00:00:00 2001 From: Joel Lonbeck Date: Sat, 6 May 2017 15:33:16 -0700 Subject: [PATCH 9/9] updated docs for condensed form --- docs/structure.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/structure.rst b/docs/structure.rst index bf2052e..db291ee 100644 --- a/docs/structure.rst +++ b/docs/structure.rst @@ -130,7 +130,7 @@ For example, here's a :ref:`structure-content` that has a chapter 1 folder conta **Condensed** -Most :ref:`types` support a condensed form in which content in each folder is stored +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: @@ -142,8 +142,7 @@ this form is most suitable for content being delivered as source text: |-02.md ... -Where the file ``01.md`` may contain the title, sub-title, intro, chunks etc. formatted appropriately so it can -be read by a client application. +Where the file ``01.md`` may contain the title, sub-title, intro, chunks, etc. for chapter 1. .. _structure-content-sort: