Skip to content

Commit

Permalink
Merge pull request #46 from neutrinog/updates
Browse files Browse the repository at this point in the history 
Updates to linking and other fixes
  • Loading branch information
@PhotoNomad0
PhotoNomad0 authored May 16, 2017
2 parents f15b9d3 + 49e79b1 commit 4cb7a8d
Show file tree
Hide file tree
Showing 5 changed files with 415 additions and 336 deletions.
136 changes: 70 additions & 66 deletions docs/container_types.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
^^^^^^
Expand All @@ -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:

Expand All @@ -68,9 +86,6 @@ Below is an example with a format of ``image/png``.
| |-02.png
| ...
...
|-front/
|-back/
...
.. _types-audio:
Expand All @@ -97,9 +112,6 @@ Below is an example with a format of ``audio/mp3``.
| |-02.mp3
| ...
...
|-front/
|-back/
...
.. _types-video:
Expand All @@ -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 <condensed>`.

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:

Expand All @@ -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 <condensed>`.

.. 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 <condensed>` 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 <linking>` 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 #
Expand All @@ -198,25 +202,25 @@ h1 heading (a single #). :ref:`Links <linking>` 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.
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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:

Expand All @@ -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 <http://ubsicap.github.io/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
Expand All @@ -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
Expand Down
Loading

0 comments on commit 4cb7a8d

Please sign in to comment.