[Help]    [Technical information]    [Rubrics]    [Credits]    [Download]    [Versions]   

Technical information

[Databases]    [Programs]    [Special characters]    [Exceptions]

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 mistake, and the ideas cannot be copyrighted, limiting our rights or the access of others to the same ideas.



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, Magyar, etc.). At this moment folders are filled up. The basic rule is that if a file is missing, the program automatically selects from the English.

Each language folder contains the same set of subfolders, which represents the parts of the printed berviary volumes: Ordinarium, Psalterium, Tempora, Sancti, Commune. For technical reasons, there are separate folders for the psalms, and for the Martyrologium.

The style and punctuation used within the text is that of the 1962 liturgical books. One space is used between sentences. 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 files itself usually are converted into Hash elements. The key is enclosed into 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.

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:

  • Ordinarium folder is the collection of the scripts describing the canonical hours. Each hour is represented by two or more files. These files are not converted into hash. A line starting with hashmark 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, Psalm 94 prepared as the Invitatory; seasonal parts for Matins (Matutinum special), Lauds, and Vespers (Major special); Minor hours (Minor special); antiphons and psalm sets (Psalmi Major|Matutinum|Minor); Marian antiphons, and special seasonal parts for Prime.

  • Transfer folder has the transfer year files. 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. For the 1960 rules, there are permanent and year to year rules. For example, the TR19602018.txt file has the appropriate transfers for the 1960 rubrics in 2018. It is an ongoing project to establish a perpetual calendar calculation algorithm which would take all anomalies into account. Please help.

  • psalms folder holds the 150 psalms, and the canticles for

    • 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.

  • Tempora folder holds the offices from the Proprium de Tempore Each office has exactly one file, and each is hash collection
    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.)

  • Sancti is the same collection for the Proprium Sanctorum
    Naming convention is:
    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 Roman Breviary, the Chrismastide offices are set within the Sancti folder.

  • Commune is the collection for Commune sanctorum. The name of the office is under the first key: Name. See below for examples.
    For practical reasons, the Officium Sanctae Mariae Sabbato is referenced by the programlet from its position among the Tempora files as C10.

  • Martyrologium contains the files named as mm-nn for the Martyrologium. Please note that the Martyrology at Prime is anticipated for the subsequent day. See credits for the sources.



The programs are written in Perl 5.6 and generate HTML. Environment variables: The following program files are used:
  • officium.pl Starts the Divinum Officium programlet. Composes the main image and also calls other programs.

  • horas.pl Common extension of the starting perl files. Interprets the special characters and prints out the officium for the selected hour.

  • special.pl Common extension of the starting perl files. Fills up the skeleton chapters with the actual content from the databases.

  • horascommon.pl Common extension of the starting perl files, also used by kalendar and edit top level files.
    The file selects the current date, and the office for any given date, deciding about the precedences.

  • dialogcommon.pl Helper set to interpret 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 List the Kalendar for the web versions and makes it possibile to select a specific date. Uses horascomon.pl and horas.pl sets.

  • edit.pl. Shows the datebase program and other files for the web versions. Uses horascommon.pl set.

  • Files is the collection of the internal databases for the web versions.


Special characters

Either the files in the Ordinarium, and the other files are using special characters to help the formatting. Each of them, with the exception of the ~ tilde sign, has to be set in the beginning of a line.

  • # hashmark in the files of Ordinarium folder or generated represent a chapter label. Special.pl program interprets and expands or limits primarily these lines. Also, they respresent the skeleton of the particular Hour.

  • [ name ] in a separate line is the key for a hash element, as mentioned earlier.

  • $ dollar sign as the first character of a line, followed by a name, represent a prayer found in Psalterium/Prayers file. These are the candidates for Popup if psalmi option is called. Some invokes an internal subroutine.

  • & sign calls an internal subroutine. If the subroutine name starts with capital letter that is listed only in all mode, if it starts with small letter, psalmi option will expand it.

  • ! An exclamation point (at the beginning of a line) will print the line with red font.

  • v. prints the following first leter as Initiale, large red font.

  • r. prints the following first letter as regular red font.

  • R.br R. V. * Ant. Benedictio These starting words are printed in regular red font.

  • double end of line represents a cell end, the printout will set a border separator.

  • _ underscore in itself in a line represents an empty line without separation.

  • ~ tilde at the end of the line represents contraction. Without it, the end of line character will be shown as <BR> in the html file.

  • ( text ) in psalm folder will print the enclosed text in small red font.

  • digits or digits:digits at the beginning of the line in psalms and readings are interpreted as verse numbers, and printed in red.

  • Common Offices (Cn) refer to the Commune Sanctorum:

    C1 : Common of ApostleC1a : Common of Evangelists   C1v : Vigil of Apostle
    C2 : Common of one MartyrC3 : Common of many Martyrs
    C4 : Common of Confessor, Bishop or Pope (with variation)C4a : Common for Doctor of the Church, bishop
    C5 : Common of Confessor not BishopC5a : Common for Doctor of the Church not a bishop
    C6 : Common of one VirginC6a : Common of many Virgins
    C7 : Common of Martyr Holy WomanC7a : Common of Holy Woman
    C8 : Common for Dedication of a ChurchC9 : Office of the Dead
    C10 : Office of the Blessed Virgin for SaturdayC11 : Common for the Blessed Virgin Mary
    other : reference to Proper officep added to the name : Eastertime Office



    Many of the files in Tempora or Sancti folders have an entry: Rule. There are the exceptions from those rule built into the Ordinarium and the Psalterium and represented by the files in those folders. A usual rules item looks like:
    ex C4;
    Psalmi Dominica
    Antiphones horas
    9 lectiones
    Each rule is a separate line and exact spelling is required, except for capitalization.

    • ex filename : everything that is not in the Proprium is taken from the named file from the Commune (Cn) or from the file in the Tempora folder (e.g. Pasc0-0 for the Easter octave)

    • vide filename : like above, but only the Matins lections and the Lauds & Vespers antiphons, versum, & oratio are taken from the named file.

    • Psalmi Dominica : The Sunday psalm set is used, except if the psalm is explicitly listed in the proprium file.

    • Antiphonas horas : Ant Laudes Antiphons are used for the minor hours:
      • 0 = Prima
      • 1 = Tertia
      • 2 = Sexta
      • 4 = Nona

    • 9 lectiones : Matins with 9 lections.

    • omit group list : Skip the named item.

    • limit group list : Special (hard coded) rules for the named items.

    • Psalm5 Vespera=nn : The last psalm in Vespers is the named one.

    • Capitulum Versum 2 [hour spec] : Capitulum is substituted with the [Versum 2] item from the propria. This occurs at all hours other than Compline if hour spec is omitted, at Lauds and Vespers if hour spec is ad Laudes et Vesperas, and at Lauds only if hour spec is ad Laudes tantum..

    • Una antiphona : Major hours are prayed under one antiphon.

    • Minores sine antiphona : Minor hours are prayed without an antiphon.

    • 1 nocturn : Matins of one nocturn only.

    • Rubrica 1570 aut Rubrica 1910 aut Rubrica Divino aut Rubrica 1960 (etc.) : Specifies usage of an element solely in one or more of these rubrical usages. The syntax is to place these conditionals in parentheses (e.g. [Lectio1](rubrica 1960), etc.)

    [Programs]    [Databases]    [Special characters]    [Exceptions]


    [Help]    [Technical information]    [Rubrics]    [Credits]    [Download]    [Versions]