calendarium-romanum 0.4.0 → 0.8.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (106) hide show
  1. checksums.yaml +5 -5
  2. data/.gitignore +4 -0
  3. data/.rspec +2 -0
  4. data/.rubocop.yml +47 -0
  5. data/.travis.yml +22 -0
  6. data/.yardopts +3 -0
  7. data/CHANGELOG.md +431 -0
  8. data/Gemfile +25 -0
  9. data/Gemfile.lock +86 -0
  10. data/README.md +598 -0
  11. data/Rakefile +16 -0
  12. data/bin/calendariumrom +4 -1
  13. data/calendarium-romanum.gemspec +31 -0
  14. data/config/locales/cs.yml +5 -0
  15. data/config/locales/en.yml +21 -14
  16. data/config/locales/es.yml +94 -0
  17. data/config/locales/fr.yml +7 -0
  18. data/config/locales/it.yml +7 -0
  19. data/config/locales/la.yml +7 -0
  20. data/data/README.md +70 -24
  21. data/data/czech-brno-cs.txt +4 -6
  22. data/data/czech-budejovice-cs.txt +4 -6
  23. data/data/czech-cechy-cs.txt +4 -5
  24. data/data/czech-cs.txt +236 -234
  25. data/data/czech-hradec-cs.txt +3 -5
  26. data/data/czech-litomerice-cs.txt +5 -7
  27. data/data/czech-morava-cs.txt +4 -5
  28. data/data/czech-olomouc-cs.txt +2 -4
  29. data/data/czech-ostrava-cs.txt +3 -5
  30. data/data/czech-plzen-cs.txt +3 -5
  31. data/data/czech-praha-cs.txt +3 -4
  32. data/data/easter_dates.txt +67 -0
  33. data/data/universal-1969-la.txt +234 -0
  34. data/data/universal-en.txt +214 -211
  35. data/data/universal-es.txt +243 -0
  36. data/data/universal-fr.txt +214 -210
  37. data/data/universal-it.txt +214 -211
  38. data/data/universal-la.txt +214 -210
  39. data/doc/data_readme.md +2 -0
  40. data/doc/images/class_diagram.png +0 -0
  41. data/doc/images/class_diagram.puml +44 -0
  42. data/doc/yard_readme.rdoc +76 -0
  43. data/lib/calendarium-romanum.rb +35 -22
  44. data/lib/calendarium-romanum/abstract_date.rb +15 -0
  45. data/lib/calendarium-romanum/calendar.rb +207 -42
  46. data/lib/calendarium-romanum/cli.rb +63 -80
  47. data/lib/calendarium-romanum/cli/comparator.rb +63 -0
  48. data/lib/calendarium-romanum/cli/date_parser.rb +30 -0
  49. data/lib/calendarium-romanum/cli/dumper.rb +68 -0
  50. data/lib/calendarium-romanum/cli/helper.rb +23 -0
  51. data/lib/calendarium-romanum/cli/querier.rb +73 -0
  52. data/lib/calendarium-romanum/cr.rb +16 -0
  53. data/lib/calendarium-romanum/data.rb +50 -20
  54. data/lib/calendarium-romanum/day.rb +208 -32
  55. data/lib/calendarium-romanum/enum.rb +42 -25
  56. data/lib/calendarium-romanum/enums.rb +124 -44
  57. data/lib/calendarium-romanum/errors.rb +4 -0
  58. data/lib/calendarium-romanum/ordinalizer.rb +23 -2
  59. data/lib/calendarium-romanum/perpetual_calendar.rb +58 -7
  60. data/lib/calendarium-romanum/rank.rb +43 -12
  61. data/lib/calendarium-romanum/rank_predicates.rb +43 -0
  62. data/lib/calendarium-romanum/sanctorale.rb +164 -24
  63. data/lib/calendarium-romanum/sanctorale_factory.rb +74 -3
  64. data/lib/calendarium-romanum/sanctorale_loader.rb +180 -0
  65. data/lib/calendarium-romanum/sanctorale_writer.rb +119 -0
  66. data/lib/calendarium-romanum/temporale.rb +226 -94
  67. data/lib/calendarium-romanum/temporale/celebration_factory.rb +107 -0
  68. data/lib/calendarium-romanum/temporale/dates.rb +84 -16
  69. data/lib/calendarium-romanum/temporale/easter_table.rb +27 -0
  70. data/lib/calendarium-romanum/temporale/extensions.rb +15 -0
  71. data/lib/calendarium-romanum/temporale/extensions/christ_eternal_priest.rb +16 -3
  72. data/lib/calendarium-romanum/temporale/extensions/dedication_before_all_saints.rb +73 -0
  73. data/lib/calendarium-romanum/transfers.rb +60 -15
  74. data/lib/calendarium-romanum/util.rb +22 -3
  75. data/lib/calendarium-romanum/version.rb +5 -1
  76. data/liturgical_law/1969_normae_universales.md +568 -0
  77. data/liturgical_law/1977_decretum_de_celebratione_baptismatis_domini.md +58 -0
  78. data/liturgical_law/1990_decretum_de_variatione_inducenda.md +67 -0
  79. data/liturgical_law/1998_notificatio_de_occurrentia.md +57 -0
  80. data/liturgical_law/2002_normae_universales.md +946 -0
  81. data/liturgical_law/2006_notification.md +37 -0
  82. data/liturgical_law/2012_declarationes.md +38 -0
  83. data/liturgical_law/README.md +74 -0
  84. metadata +50 -28
  85. data/lib/calendarium-romanum/sanctoraleloader.rb +0 -115
  86. data/spec/abstract_date_spec.rb +0 -62
  87. data/spec/calendar_spec.rb +0 -330
  88. data/spec/celebration_spec.rb +0 -23
  89. data/spec/cli_spec.rb +0 -26
  90. data/spec/colour_spec.rb +0 -17
  91. data/spec/data_spec.rb +0 -23
  92. data/spec/date_spec.rb +0 -61
  93. data/spec/dates_spec.rb +0 -45
  94. data/spec/day_spec.rb +0 -59
  95. data/spec/enum_spec.rb +0 -51
  96. data/spec/i18n_spec.rb +0 -59
  97. data/spec/ordinalizer_spec.rb +0 -22
  98. data/spec/perpetual_calendar_spec.rb +0 -91
  99. data/spec/rank_spec.rb +0 -57
  100. data/spec/readme_spec.rb +0 -52
  101. data/spec/sanctorale_factory_spec.rb +0 -42
  102. data/spec/sanctorale_spec.rb +0 -191
  103. data/spec/sanctoraleloader_spec.rb +0 -171
  104. data/spec/season_spec.rb +0 -17
  105. data/spec/spec_helper.rb +0 -35
  106. data/spec/temporale_spec.rb +0 -519
@@ -0,0 +1,16 @@
1
+ require 'rspec/core/rake_task'
2
+ RSpec::Core::RakeTask.new(:spec)
3
+
4
+ desc 'Run specs with each fully supported locale'
5
+ task :spec_all_locales do
6
+ %w(en la cs fr it).each do |locale|
7
+ sh "LOCALE=#{locale} rake spec"
8
+ end
9
+ end
10
+
11
+ desc 'Generates calendar dumps for regression tests anew'
12
+ task :regression_refresh do
13
+ 2020.upto(2030).each do |year|
14
+ sh "ruby -Ilib bin/calendariumrom dump #{year} > spec/regression_dumps/#{year}.txt"
15
+ end
16
+ end
@@ -1,6 +1,9 @@
1
- #!/bin/env ruby
1
+ #!/usr/bin/env ruby
2
2
 
3
3
  require 'calendarium-romanum'
4
4
  require 'calendarium-romanum/cli'
5
5
 
6
+ # Don't warn about enforcing locales in the CLI.
7
+ I18n.config.enforce_available_locales = true
8
+
6
9
  CalendariumRomanum::CLI.start ARGV
@@ -0,0 +1,31 @@
1
+ # -*- coding: utf-8 -*-
2
+ require_relative 'lib/calendarium-romanum/version'
3
+
4
+ Gem::Specification.new do |s|
5
+ s.name = 'calendarium-romanum'
6
+ s.version = CalendariumRomanum::VERSION
7
+ s.date = CalendariumRomanum::RELEASE_DATE.to_s
8
+ s.summary = 'Roman Catholic liturgical calendar computations'
9
+
10
+ s.description = 'calendar computations according to the Roman Catholic liturgical calendar as instituted by MP Mysterii Paschalis of Paul VI (1969) and defined in General Norms for the Liturgical Year and the Calendar and other documents of liturgical legislation.'
11
+
12
+ s.authors = ['Jakub Pavlík']
13
+ s.email = 'jkb.pavlik@gmail.com'
14
+ s.files = `git ls-files -z`.split("\x0").reject do |f|
15
+ f.match(%r{^(test|spec|features)/})
16
+ end
17
+ s.executables = %w(calendariumrom)
18
+ s.homepage = 'http://github.com/igneus/calendarium-romanum'
19
+ s.licenses = ['LGPL-3.0', 'MIT']
20
+ s.metadata = {
21
+ 'documentation_uri' => 'https://www.rubydoc.info/gems/calendarium-romanum/',
22
+ }
23
+
24
+ s.required_ruby_version = '>= 2.0'
25
+
26
+ s.add_dependency 'thor', '~> 0.18'
27
+ s.add_dependency 'i18n', '~> 0.6'
28
+ s.add_dependency 'roman-numerals', '~> 0.3'
29
+ s.add_development_dependency 'rake', '~> 12.0'
30
+ s.add_development_dependency 'rspec', '~> 3.5'
31
+ end
@@ -4,6 +4,7 @@ cs:
4
4
  advent: Doba adventní
5
5
  christmas: Doba vánoční
6
6
  lent: Doba postní
7
+ triduum: Velikonoční triduum
7
8
  easter: Doba velikonoční
8
9
  ordinary: Liturgické mezidobí
9
10
  solemnity:
@@ -22,16 +23,20 @@ cs:
22
23
  holy_trinity: Nejsvětější Trojice
23
24
  corpus_christi: Těla a krve Páně
24
25
  sacred_heart: Nejsvětějšího srdce Ježíšova
26
+ mother_of_church: Panny Marie, Matky církve
25
27
  immaculate_heart: Neposkvrněného Srdce Panny Marie
26
28
  christ_king: Ježíše Krista krále
29
+ saturday_memorial_bvm: Sobotní památka Panny Marie
27
30
  extension:
28
31
  christ_eternal_priest: Ježíše Krista, nejvyššího a věčného kněze
32
+ dedication: Výročí posvěcení kostela
29
33
  ordinary:
30
34
  sunday: '%{week} neděle v mezidobí'
31
35
  ferial: '%{weekday} %{week} týdne v mezidobí'
32
36
  advent:
33
37
  sunday: '%{week} neděle adventní'
34
38
  ferial: '%{weekday} po %{week} neděli adventní'
39
+ before_christmas: '%{day} prosince'
35
40
  christmas:
36
41
  nativity_octave:
37
42
  ferial: '%{day} den v oktávu Narození Páně'
@@ -4,32 +4,39 @@ en:
4
4
  advent: Advent
5
5
  christmas: Christmas Season
6
6
  lent: Lent
7
+ triduum: Easter Triduum
7
8
  easter: Easter Season
8
9
  ordinary: Ordinary Time
9
10
  solemnity:
10
- nativity: The Nativity of the Lord
11
- holy_family: The Holy Family of Jesus, Mary and Joseph
12
- mother_of_god: Octave Day of Christmas, of Mary, Mother of God
13
- epiphany: The Epiphany of the Lord
11
+ nativity: Christmas
12
+ holy_family: The Holy Family
13
+ mother_of_god: Mary, Mother of God (Octave of Christmas)
14
+ epiphany: The Epiphany
14
15
  baptism_of_lord: The Baptism of the Lord
15
16
  ash_wednesday: Ash Wednesday
16
- palm_sunday: Palm Sunday of the Passion of the Lord
17
- good_friday: Friday of the Passion of the Lord
17
+ palm_sunday: Passion Sunday (Palm Sunday)
18
+ good_friday: Good Friday
18
19
  holy_saturday: Holy Saturday
19
- easter_sunday: Easter Sunday of the Resurrection of the Lord
20
- ascension: Ascension of the Lord
21
- pentecost: Pentecost Sunday
22
- holy_trinity: The Most Holy Trinity
23
- corpus_christi: The Most Holy Body and Blood of Christ
24
- sacred_heart: The Most Sacred Heart of Jesus
25
- immaculate_heart: Immaculate Heart of Mary
26
- christ_king: Our Lord Jesus Christ, King of the Universe
20
+ easter_sunday: Easter Sunday
21
+ ascension: The Ascension
22
+ pentecost: Pentecost
23
+ holy_trinity: Trinity Sunday
24
+ corpus_christi: Corpus Christi (The Body and Blood of Christ)
25
+ sacred_heart: The Sacred Heart of Jesus
26
+ mother_of_church: Mary, Mother of the Church
27
+ immaculate_heart: The Immaculate Heart of Mary
28
+ christ_king: Christ The King
29
+ saturday_memorial_bvm: The Memorial of the Blessed Virgin Mary on Saturday
30
+ extension:
31
+ christ_eternal_priest: Our Lord Jesus Christ, The Eternal High Priest
32
+ dedication: Anniversary of Dedication
27
33
  ordinary:
28
34
  sunday: '%{week} Sunday in Ordinary Time'
29
35
  ferial: '%{weekday}, %{week} week in Ordinary Time'
30
36
  advent:
31
37
  sunday: '%{week} Sunday of Advent'
32
38
  ferial: '%{weekday}, %{week} week of Advent'
39
+ before_christmas: '%{day} December'
33
40
  christmas:
34
41
  nativity_octave:
35
42
  ferial: '%{day} day of Christmas Octave'
@@ -0,0 +1,94 @@
1
+ es:
2
+ temporale:
3
+ season:
4
+ advent: Adviento
5
+ christmas: Navidad
6
+ lent: Cuaresma
7
+ triduum: Triduo Pascual
8
+ easter: Pascua
9
+ ordinary: Tiempo Ordinario
10
+ solemnity:
11
+ nativity: Natividad
12
+ holy_family: La Sagrada Familia
13
+ mother_of_god: María, Madre de Dios (Octava de Navidad)
14
+ epiphany: La Epifanía
15
+ baptism_of_lord: El Bautismo del Señor
16
+ ash_wednesday: Miércoles de Ceniza
17
+ palm_sunday: Domingo de Ramos
18
+ good_friday: Viernes Santo
19
+ holy_saturday: Sábado Santo
20
+ easter_sunday: Domingo de Resurrección
21
+ ascension: La Ascensión
22
+ pentecost: Pentecostés
23
+ holy_trinity: Domingo de Trinidad
24
+ corpus_christi: Corpus Christi (Cuerpo y Sangre de Cristo)
25
+ sacred_heart: El Sagrado Corazón de Jesús
26
+ mother_of_church: María, Madre de la Iglesia
27
+ immaculate_heart: El Inmaculado Corazón de María
28
+ christ_king: Cristo Rey
29
+ saturday_memorial_bvm: The Memorial of the Blessed Virgin Mary on Saturday
30
+ extension:
31
+ christ_eternal_priest: Jesucristo, Sumo y Eterno Sacerdote
32
+ dedication: Aniversario Dedicación de la iglesia
33
+ ordinary:
34
+ sunday: '%{week} Domingo del Tiempo Ordinario'
35
+ ferial: '%{weekday}, %{week} semana del Tiempo Ordinario'
36
+ advent:
37
+ sunday: '%{week} Domingo de Adviento'
38
+ ferial: '%{weekday}, %{week} semana de Adviento'
39
+ before_christmas: '%{day} de Diciembre'
40
+ christmas:
41
+ nativity_octave:
42
+ ferial: '%{day} día de la Octava de Navidad'
43
+ sunday: '%{week} Sunday después de la Natividad del Señor'
44
+ ferial: '%{weekday} después de la Octava de Navidad'
45
+ after_epiphany:
46
+ ferial: '%{weekday} después de la Epifanía'
47
+ lent:
48
+ after_ashes:
49
+ ferial: '%{weekday} después del Miércoles de Ceniza'
50
+ sunday: '%{week} Domingo de Cuaresma'
51
+ ferial: '%{weekday}, %{week} semana de Cuaresma'
52
+ holy_week:
53
+ ferial: '%{weekday} de la Semana Santa'
54
+ easter:
55
+ octave:
56
+ ferial: '%{weekday} de Pascua'
57
+ sunday: '%{week} Domingo de Pascua'
58
+ ferial: '%{weekday}, %{week} semana de Pascua'
59
+ rank:
60
+ '1_1': Triduo Pascual
61
+ '1_2': Días litúrgicos primarios
62
+ '1_3': Solemnidades en el Calendario General
63
+ '1_4': Solemnidades
64
+ '2_5': Fiestas del Señor en el Calendario General
65
+ '2_6': Unprivileged Sundays
66
+ '2_7': Fiestas de Santos en el Calendario General
67
+ '2_8': Fiestas
68
+ '2_9': Días Privilegiados
69
+ '3_10': Memorias Obligatorias en el Calendario General
70
+ '3_11': Memorias Obligatorias
71
+ '3_12': Memorias Opcionales
72
+ '3_13': Días
73
+ '4_0': Conmemoraciones
74
+ short:
75
+ solemnity: solemnidad
76
+ feast: fiesta
77
+ sunday: Domingo
78
+ memorial: memoria
79
+ memorial_opt: memoria opcional
80
+ ferial: ferial
81
+ commemoration: conmemoración
82
+ weekday:
83
+ '0': Domingo
84
+ '1': Lunes
85
+ '2': Martes
86
+ '3': Miércoles
87
+ '4': Jueves
88
+ '5': Viernes
89
+ '6': Sábado
90
+ colour:
91
+ violet: violeta
92
+ white: blanco
93
+ green: verde
94
+ red: rojo
@@ -4,6 +4,7 @@ fr:
4
4
  advent: "Temps de l'Avent"
5
5
  christmas: Temps de Noël
6
6
  lent: Temps du Carême
7
+ triduum: Triduum pascal
7
8
  easter: Temps de Pâques
8
9
  ordinary: Temps ordinaire
9
10
  solemnity:
@@ -22,14 +23,20 @@ fr:
22
23
  holy_trinity: La Très Sainte Trinité
23
24
  corpus_christi: Le Très Saint Corps et Sang du Christ
24
25
  sacred_heart: Le Sacré-Coeur de Jésus
26
+ mother_of_church: Sainte Marie, Mère de l’Eglise
25
27
  immaculate_heart: Le Coeur Immaculé de Marie
26
28
  christ_king: Notre Seigneur Jésus Christ, Roi de l'Univers
29
+ saturday_memorial_bvm: Mémoire de Sainte-Marie le samedi
30
+ extension:
31
+ christ_eternal_priest: Jésus Christ, prêtre éternel et souverain
32
+ dedication: Anniversaire de la Dédicace de l'église
27
33
  ordinary:
28
34
  sunday: '%{week} Dimanche de Temps Ordinaire'
29
35
  ferial: '%{weekday}, %{week} semaine de Temps Ordinaire'
30
36
  advent:
31
37
  sunday: '%{week} Dimanche de l''Avent'
32
38
  ferial: '%{weekday}, %{week} semaine de L''Avent'
39
+ before_christmas: '%{day} décembre'
33
40
  christmas:
34
41
  nativity_octave:
35
42
  ferial: 'Jour %{day} de l''Octave de Noël'
@@ -4,6 +4,7 @@ it:
4
4
  advent: Tempo di Avvento
5
5
  christmas: Tempo di Natale
6
6
  lent: Tempo di Quaresima
7
+ triduum: Triduo Pasquale
7
8
  easter: Tempo pasquale
8
9
  ordinary: Tempo ordinario
9
10
  solemnity:
@@ -22,14 +23,20 @@ it:
22
23
  holy_trinity: Santissima Trinità
23
24
  corpus_christi: Santissimo Corpo e Sangue di Cristo
24
25
  sacred_heart: Sacro Cuore di Gesù
26
+ mother_of_church: Maria Madre della Chiesa
25
27
  immaculate_heart: Cuore Immacolato di Maria
26
28
  christ_king: "Nostro Signore Gesù Cristo Re dell'universo"
29
+ saturday_memorial_bvm: Memoria di santa Maria in sabato
30
+ extension:
31
+ christ_eternal_priest: Nostro Signore Gesù Cristo Sommo e Eterno Sacerdote # I didn't find an official translation anywhere (as the feast is not celebrated in Italy) and had to translate myself - readers proficient in Italian are kindly asked for a check
32
+ dedication: Anniversario della Dedicazione della chiesa
27
33
  ordinary:
28
34
  sunday: '%{week} Domenica del Tempo Ordinario'
29
35
  ferial: '%{weekday} della %{week} settimana del Tempo Ordinario'
30
36
  advent:
31
37
  sunday: '%{week} Domenica Avvento'
32
38
  ferial: '%{weekday}, %{week} Avvento'
39
+ before_christmas: '%{day} dicembre'
33
40
  christmas:
34
41
  nativity_octave:
35
42
  ferial: '%{day}, Ottava di Natale'
@@ -4,6 +4,7 @@ la:
4
4
  advent: Tempus Adventus
5
5
  christmas: Tempus Nativitatis
6
6
  lent: Tempus Quadragesimae
7
+ triduum: Triduum Paschale
7
8
  easter: Tempus Paschale
8
9
  ordinary: Tempus per annum
9
10
  solemnity:
@@ -22,14 +23,20 @@ la:
22
23
  holy_trinity: Sanctissimae Trinitatis
23
24
  corpus_christi: Sanctissimi Corporis et Sanguinis Christi
24
25
  sacred_heart: Sacratissimi Cordis Iesu
26
+ mother_of_church: B. Mariae Virginis Ecclesiae Matris
25
27
  immaculate_heart: Immaculati Cordis B. Mariae Virginis
26
28
  christ_king: Domini nostri Iesu Christi universorum regis
29
+ saturday_memorial_bvm: Memoria Sanctae Mariae in Sabbato
30
+ extension:
31
+ christ_eternal_priest: Domini nostri Iesu Christi Summi et Aeterni Sacerdotis
32
+ dedication: Anniversarium dedicationis ecclesiae
27
33
  ordinary:
28
34
  sunday: 'Dominica %{week} per annum'
29
35
  ferial: '%{weekday}, hebdomada %{week} per annum'
30
36
  advent:
31
37
  sunday: 'Dominica %{week} Adventus'
32
38
  ferial: '%{weekday}, hebdomada %{week} Adventus'
39
+ before_christmas: 'Die %{day} decembris'
33
40
  christmas:
34
41
  nativity_octave:
35
42
  ferial: 'De die %{day} infra octavam Nativitatis'
@@ -23,7 +23,7 @@ a number from range 1-12.
23
23
  A calendar entry is a line of this format:
24
24
 
25
25
  ```
26
- [MONTH/]DAY [RANK] [COLOUR] : TITLE
26
+ [MONTH/]DAY [RANK] [COLOUR] [IDENTIFIER] : TITLE
27
27
  ```
28
28
 
29
29
  If the calendar entry is preceded by a month heading, MONTH is
@@ -33,25 +33,27 @@ DAY must be a number valid as a possible date in the given month.
33
33
  (29 is valid in February, as it sometimes occurs;
34
34
  31 is not valid in April, as there is never April 31st.)
35
35
 
36
- RANK is a single letter m=memorial, f=feast, s=solemnity.
37
- If omitted, optional memorial is assumed.
38
-
39
- When it is desirable to specify rank of a celebration
40
- with greater precision, e.g. in order to distinguish feasts
41
- inscribed in the General Roman Calendar from proper feasts,
42
- use rank number instead of a rank letter.
43
- Rank priority numbers are defined in
44
- [lib/calendarium-romanum/enums.rb](../lib/calendarium-romanum/enums.rb)
45
- and correspond to section and subsection numbers in
46
- the Table of Liturgical Days
47
- (see end of the [General Norms](https://www.ewtn.com/library/CURIA/CDWLITYR.HTM)).
48
- This is why the sequence is non-continuous:
49
- `1.4` is followed by `2.5` and `2.9` by `3.10`.
36
+ RANK is a rank code, which can have several forms:
37
+
38
+ 1. *no* rank code - optional memorial will be assumed
39
+ 1. single letter: `m` = memorial, `f` = feast, `s` = solemnity
40
+ 1. rank priority number, e.g. `1.3` (defined in
41
+ [lib/calendarium-romanum/enums.rb](../lib/calendarium-romanum/enums.rb),
42
+ and correspond to section and subsection numbers in the Table of Liturgical Days
43
+ in the [General Norms](https://www.ewtn.com/library/CURIA/CDWLITYR.HTM))
44
+ 1. letter and a priority number, e.g. `s1.3`
45
+ 1. letter with a specifying suffix, e.g. `sp`: suffix `p` distinguishes
46
+ proper solemnities/feasts/memorials from those inscribed in the General
47
+ Roman Calendar, suffix `l` (only allowed in combination `fl`)
48
+ distinguishes feasts of the Lord from other feasts inscribed
49
+ in the General Roman Calendar.
50
+
51
+ Single letter codes are used to encode ranks of most celebrations
52
+ inscribed in the General Roman Calendar, the other forms for other
53
+ ranks (proper celebrations, feasts of the Lord etc.).
50
54
 
51
55
  The example below presents pairs of equivalent lines,
52
56
  the first one specifying rank by letter, the second one by number.
53
- Rank letters are always interpreted as if the celebration
54
- was inscribed in the General Roman Calendar.
55
57
 
56
58
  ```
57
59
  3/19 s : Saint Joseph Husband of the Blessed Virgin Mary
@@ -69,20 +71,22 @@ was inscribed in the General Roman Calendar.
69
71
 
70
72
  As an example of a proper celebration (which requires rank number
71
73
  when exact ranking is important) let's use solemnity of the
72
- principal patron of Bohemia, martyr duke St. Wenceslas:
74
+ principal patron of Bohemia, martyr duke St. Wenceslas
75
+ (three alternative ways to encode the same rank of a proper solemnity):
73
76
 
74
77
  ```
75
78
  9/28 1.4 R : Sv. Václava, mučedníka, hlavního patrona českého národa
79
+ 9/28 s1.4 R : Sv. Václava, mučedníka, hlavního patrona českého národa
80
+ 9/28 sp R : Sv. Václava, mučedníka, hlavního patrona českého národa
76
81
  ```
77
82
 
78
- When you have dificulties remembering meanings of the numbers,
79
- but are comfortable with rank letters, it might be helpful for you
80
- to use rank numbers *alongside* the letters.
81
- This is supported too, you will find this format used throughout
82
- the bundled data files.
83
+ Feasts of the Lord similarly require a more specific rank code
84
+ than the general `f`:
83
85
 
84
86
  ```
85
- 9/28 s1.4 R : Sv. Václava, mučedníka, hlavního patrona českého národa
87
+ 11/9 2.5 lateran_basilica : Dedication of the Lateran basilica
88
+ 11/9 f2.5 lateran_basilica : Dedication of the Lateran basilica
89
+ 11/9 fl lateran_basilica : Dedication of the Lateran basilica
86
90
  ```
87
91
 
88
92
  COLOUR is a single letter R=red, W=white (G=green, V=violet normally
@@ -92,8 +96,47 @@ If not specified, white is default.
92
96
 
93
97
  TITLE is a simple text - title of the celebration - without formatting.
94
98
 
99
+ IDENTIFIER is a single "word" consisting of lowercase letters and
100
+ underscores, at least 2 characters long.
101
+ It is optional and serves as a unique machine-readable identifier
102
+ of the given celebration.
103
+
95
104
  There may be several entries for a day (optional memorials).
96
105
 
106
+ ### YAML metadata
107
+
108
+ At the beginning of the file there may be a "YAML front matter"
109
+ (cf. [use of YFM in Jekyll][yfm]) -
110
+ a YAML document with arbitrary metadata.
111
+ The front matter is parsed when loading the data file
112
+ and it's contents are available to the application code
113
+ in `Sanctorale#metadata`.
114
+
115
+ Top-level structure of the document should be a Hash
116
+ (or "mapping" in the [YAML specification][yamlspec]'s vocabulary).
117
+ It may contain whatever the author finds useful.
118
+ A few fields are suggested:
119
+
120
+ * `title` - name of the calendar in the language of it's contents
121
+ (suitable for the end user)
122
+ * `description` - description of the contents in English (suitable for
123
+ people who may not understand the language of the contents,
124
+ e.g. maintainers of multi-language calendar applications)
125
+ * `locale` - 2-character code of the content's language
126
+ (may be used by applications to automatically select a matching
127
+ locale for temporale feast names)
128
+ * `country` - ISO 3166 alpha2 country code (only for country-specific
129
+ data)
130
+ * `province` - name of ecclesiastical province (only for
131
+ province-specific data)
132
+ * `diocese` - name of diocese (only for diocese-specific data)
133
+ * `extends` - either String or (if multiple parents are needed)
134
+ Array ("sequence" in the [YAML specification][yamlspec]'s vocabulary)
135
+ of more general data file(s) the given file extends
136
+ (usually as relative filesystem paths; can be used by applications
137
+ to automatically load hierarchies of sanctorale data -
138
+ see `SanctoraleFactory.load_with_parents`)
139
+
97
140
  ## Check your data
98
141
 
99
142
  Included is a script controlling correctness of data files
@@ -143,3 +186,6 @@ end
143
186
 
144
187
  layered_sanctorale = CR::SanctoraleFactory.create_layered(*layers)
145
188
  ```
189
+
190
+ [yfm]: https://jekyllrb.com/docs/front-matter/
191
+ [yamlspec]: https://yaml.org/spec/1.2/spec.html