Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates to linking and other fixes #46

Merged
merged 11 commits into from
May 16, 2017
Merged

Updates to linking and other fixes #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
dcb13c3
Merge branch 'master' of github.com:unfoldingWord-dev/Resource-Container
da1nerd May 2, 2017
0ab1ff9
Merge branch 'master' of github.com:unfoldingWord-dev/Resource-Container
da1nerd May 4, 2017
b225b8f
updated project structure, and condensed vs expanded
da1nerd May 4, 2017
a7f862e
removed simple table of contents
da1nerd May 4, 2017
f46d30f
fixes #44 part of #43 and #38
da1nerd May 5, 2017
2027517
updated notes
da1nerd May 5, 2017
cf49e3d
tweaks, updating toc docs
da1nerd May 5, 2017
ceb1428
improvements to manifest docs
da1nerd May 5, 2017
c75e2d1
improvements to container types docs
da1nerd May 6, 2017
402552c
updates to linking
da1nerd May 6, 2017
49e79b1
updated docs for condensed form
da1nerd May 6, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 70 additions & 66 deletions docs/container_types.rst
View file
Open in desktop
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