Clone this wiki locally
Sefaria's original design gives special structure to commentary texts which offers some benefits (automatic linking to basetexts, ability to generate new
Index records on the fly) but requires a special structure which can be limiting. In cases where we have commentary texts that don't match these limitations, we begun using second method of creating commentary texts which is called in the
Commentary2. We intend to deprecate the original commentary structure and add features to general Index records to compensate, but for the time being we support both.
Original Style Commentaries
Original style commentaries on Sefaria function by having a storing a single
Index record for each commentator. These commentator
Index records can combine with any other
Index record of a text, to create a virtual Index record for a commentary text.
For example, if we have a commentator record for
Rashi and a text
Index record for
Shabbat, then Sefaria will understand
Rashi on Shabbat to be a commentary on
Shabbat. The structure of
Rashi on Shabbat will be identical to the structure of the
Shabbat with one addition level of depth in the terminal nodes called
Comment. This allows for e.g., multiple distinct comments to be stored for a single segment of base text.
No index record is actually stored in the database for
Rashi on Shabbat -- they are generated in code on the fly. This means, that there is no enforcing which commentaries actually exist,
Rashi on Zohar will be accepted as well as
Rashi on Genesis.
When text is saved from a virtual commentary index, links are created automatically to its base text. The links are created by matching the structure of commentary text to its base. Hence when posting commentaries, each comment needs to be slotted in to the appropriate location according to its base text. If there is a segment or section for which the commentary does not say anything, these sections need to be left blank in the commentary text.
Because they impose restrictions on the structure of a commentary text, some commentaries don't fit in to Sefaria's original design. In order to allow commentaries of different structures to still appear to users of the site as commentaries (rather than being displayed in different category), the category "Commentary2" can be used to make any text appear like a commentary. These texts are functionally the same as ay other text in Sefaria (they can be simple or complex), but the special top level category
Commentary2 allows them to appear like other commentaries.
Commentary2 texts do not have autolinking.
categoriesfield should include 3 items (1) "Commentary2", (2) the top level category of the base text and (3) the name of the commentator. E.g.,
["Commentary2", "Mishnah", "Rambam"].
- Because the categories field is stored only in the English, the commentaor name must have a translation available in the
hebrew_termsfunction of hebrew.py.
- Commentary2 texts with titles that follow the form "Commentator on Book", will be ordered in the table of contents according to the order of the base book.
- Commentary2 texts with titles of different forms are allowed (e.g., "Rambam's Introduction to the Mishnah"). In order to order these texts among others in the table of contents, they require an explicit
orderfield on the index record. This fields needs to be a an array containing a single number (integer or float) which will position it between other records are desired. Examining the table of contents api will show other existing order numbers to be slotted between. Although some books have multiple number in their order field, only the first is examined in order the TOC, hence only one number is needed here.