This part of the help manual is written explicitly for encouraging anyone interested in the topic to write his/her own system, using whatever he/she wants from these ideas. It is also meant to provide a general overview of how the programlet is internally structured.
The only restriction is that we at The Divinum Officium Project have no legal responsibility for any errata, and the ideas cannot be copyrighted, limiting our rights or the access of others to the
The databases are files, which contain the text of the Breviary.
For easier understanding and handling, they are organized into folders. Most files use UTF-8 encoding (which is preferred) but some files may still remain in Win-1252 encoding. If editing files, please be aware of this difference, as it can and will effect the appearance of text. If editing via GitHub in a browser, GitHub will automatically transcode files to UTF-8.
The top level folders are folders for the languages (Latin, English, French, etc.). The basic rule is that if a file is missing for a specific (modern) language, the program automatically selects the language text from the English.
Each language folder contains the same set of subfolders, which represents the parts of the printed breviary volumes: Ordinarium, Psalterium, Tempora, Sancti, Commune. For technical reasons, there are separate folders for the psalms and for the Martyrologium. The Latin folder "psalms" contains unaccented psalms, while "psalms1" contains the accented psalms, and "PiusXII" contains the Pius XII psalter. Folders marked "M" are used to display the Monastic version of the Office.
The style and punctuation used within the text is that of the 1962 liturgical books (i.e. natalicio is preferred to natalitio, abicere to abjicere, etc.), with the exception that one space is used between sentences, and no space is placed before a colon or other punctuation. In accordance with the principles sent to the typographers of the 1960 editiones typicae, the letter J in the 1960 rubrics is transformed to the letter I. (Sacrae Congregatio Rituum, "Ordinationes ad librorum liturgicorum editores", 26.VI.1960) The programlet is capable of automatically making certain typographical and rubrical changes to account for these and other variations in the 1960 rubrics.
The files itself usually are converted into hash elements, e.g. [Ant Matutinum], [Capitulum Nona], etc.
The key is enclosed within square brackets [ ... ] which is a separate line followed by the body of the element. For instance, [Ant 2] refers to the Benedictus antiphon at Lauds, while [Lectio93] normally refers to the 9th (hagiographical) reading of a commemorated saint (pre-1960), which became the 3rd reading at Matins on 3rd class feasts under 1960 rubrics.
In all cases, the hash and key are on one line (followed by any conditional rubrics within parentheses), and the text is placed on the subsequent line after a single carriage return.
These elements are read and composed by the programlet.
The folder and files can be viewed within the GitHub repository, which shows the files
in the following folders in the directory ~/horas and, subsequently, ~/horas/Latin (or any modern language):
- The Ordinarium folder is the collection of the scripts structuring the canonical hours.
Each hour is represented by two or more files. These files are not converted into hash. A line starting with # organizes the content. These files are used by
special.pl program file. If necessary, there are separate files for the 1960 (name ending with 'r') or Tridentine version (name ending with 't') or for Paschal time (name ending with 'p'.)
- Psalterium folder holds the information usually printed
in the Ordinarium and Psalterium sections of the Breviarium Romanum. Prayers.txt
contains the common prayers. The rest contains the Benedictions, Doxologies, specific forms of the Invitatory, seasonal parts for Matins (Matutinum special), Lauds & Vespers (Major special);
Minor hours (Minor special); antiphons and psalm sets (Psalmi Major|Matutinum|Minor), Marian antiphons, and special seasonal parts for Prime (Prima special).
- Psalms folder holds the 150 psalms, and the
- 210-216 = Laudes 1;
- 220-226 = Laudes 2;
- 231-234 = New Testament canticles and the Quicumque
The verses are numbered by chapter:verse numbers, and anything in parentheses is printed in small red font.
- The Tempora folder holds the offices from the Proprium de Tempore. Each office has exactly one file, and each is a hash collection. The naming convention is:
Season name w-d where w is the week of the season, and d is the day of week. (Example: Pent04-2 represents Tuesday of the 4th week after Pentecost. Similarly, 085-0 represents Sunday of the 5th week of August.)
- Sancti is the same collection of offices as found in the Proprium Sanctorum. The naming convention is:
mm-nn where mm is the month, nn is the day. (Example: 07-26 represents July 26, Feast of St. Anne.) For practical reasons, unlike in the Missale Romanum or Breviarium Romanum, the Christmastide offices are placed within the Sancti folder. Files are marked with certain letters for their usage within certain rubrical structures:
- r = 1960 rubrics;
- t = 1570 rubrics;
- o = 1910 rubrics;
- n = 1960 rubrics with new calendar additions;
- p = Paschaltide
Each feast is assigned a number for ranking purposes, which can be augmented by a decimal to slightly increase or decrease the rank. Generally, the following enumeration is used:
- 1 = Simplex;
- 2 = Semiduplex;
- 3 = Duplex;
- 4 = Duplex majus;
- 5 = Duplex II Classis;
- 6 = Duplex I Classis
- Commune is the collection for Commune Sanctorum. The name of the office is under the first key: Name. See below for examples.
- Martyrologium contains the files named as mm-nn (in the same way as the Sancti folder) for the
Martyrologium. Please note that the Martyrology at Prime is anticipated for the subsequent day. In the Latin text, there exist different folders containing the Martyrology corresponding to the different rubrical structures. For instance, the folder ~/Latin/Martyrologium1960 represents the Martyrology as used in the 1960 rubrics, while ~/Latin/Martyrologium1955R will display that from the 1955 rubrics. Please see credits for the sources.
- Tabulae contains the transfer tables and are found in the ~/Latin folder. The Tr=Transfer files have
lines, where 'filename' is the name of the office (from the Proprium de Tempore or Proprium Sanctorum) and the
mm-nn is the date in the given year to which it is transfered. It is an ongoing project to establish a perpetual calendar calculation algorithm which would take all anomalies into account. Please help.
- Files beginning with K give the permanent Sanctoral calendar for a given rubrical structure (KM = Monastic, KNC = New calendar, K1954 = Divino Afflatu, etc.)
- Files beginning with Tr (Tr1570, Tr1960, etc.) and without a year indicated list the perpetually-transferred files in the Tempora directory for a given rubrical structure.
- Files beginning with Str with a year indicated are the Scripture transfer tables for Matins for that year, and appear in the format Str(rubric)yyyy.txt. For example, Matins Scripture transfers for 2020 in Divino Afflatu rubrics are found in the file StrDA2020.txt.
- Files beginning with Tr with a year indicated are the transfer tables for that year, and appear in the format Tr(rubric)yyyy.txt Therefore, transfers for the year 2021 under Newcalendar rubrics are found in the file TrNewcal2021.txt.
The programs are written in Perl 5.6 and generate HTML.
The following program files are used:
- officium.pl Starts the Divinum Officium programlet. Composes the main page and
also calls upon other scripts.
Main Perl Scripts
- horas.pl Interprets the special characters and prints out the Officium for the selected hour.
- special.pl Fills up the skeleton chapters with the actual content from the databases.
- horascommon.pl The file selects the current date, and the office for any given date, and provides rules for precedence.
Auxiliary Perl Scripts
- dialogcommon.pl Interprets the defaults and setup.
- webdia.pl Helper set to generate the dialog table, special html parts of the office tables, and also reads/writes cookies.
- setup.pl Generates the dialog box to set the parameters for web versions.
- popup.pl Generates a popup window if requested by the horas page.
- kalendar.pl Displays the Kalendar and makes it possibile to select a specific date. Uses horascomon.pl and horas.pl script sets.
- edit.pl. Shows the datebase program and other files for the web versions. Uses horascommon.pl.
- Files (i.e. those found in ~/web/www/horas) is the collection of the internal databases for the
web versions, broken down by language.
All .txt files employ special characters to properly format the Hours. Each of them, with the exception of the ~ tilde sign, has to be set in the beginning of a line.