.. | ||
test | ||
centuries.lua | ||
LICENSE.txt | ||
Makefile | ||
README.md |
Formatting references to centuries
centuries
is a Lua filter for Pandoc that automatically formats references to centuries in a homogeneous, yet flexible way across the document. Its numerous customization options should make it adaptable to any language.
Terminology
In “20th century AD”, we call “20” the number, “th” the suffix, “ century” (including the space) the unit and “ AD” (including the space) the era.
Basic use
Most of the time, you only have to put the century number into a span with class .cty
. You can prefix it with +
or -
if you want to indicate explicitly if it is in the reference era (by default the Christian era) or before it.
Rome conquered Gaul in the [-1]{.cty}.
Emperor Hadrian lived in the [+2]{.cty}.
Two world wars occurred during the first half of the [20]{.cty}.
Output with default configuration:
Rome conquered Gaul in the 1rst century BC.
Emperor Hadrian lived in the 2nd century AD.
Two world wars occurred during the first half of the 20th century.
You can set the attribute ctyunit
to sg
if you want the unit to be singular (the default in the default configuration), pl
for the plural form, and none
if you don't want to display the unit.
During the [4]{.cty ctyunit=none}–[8]{.cty ctyunit=pl}.
During the 4th–8th centuries.
There is an other attribute ctyera
as well. For more details, see below Formatting the era.
Customization options
You can customize the behavior of the filter through metadata fields. The metadata in test/test-english.lua
reflects the defaults, except for cty-other-eras
. For an example of user-defined configuration, see test/test-french.lua
.
Formatting the number
The value of the field cty-numeral-type
determines whether the number must be displayed as an arabic
or roman
numeral or spelled-out
(e.g. “twenty-first”).
In the latter case, you may provide a list of ordinals as the value of the field cty-spelled-out-ordinals
(see the test files for examples). The list needs to go as far as the highest century number you use: so, if you have to speak about the “thirtieth century BC”, you will have to provide the list of the 30 first ordinal numbers.
To determine whether the numeral should be printed in lowercase
, uppercase
or smallcaps
, you can set the cty-numeral-style
field to the desired value.
Formatting the suffix
The value of cty-ordinal-suffixes
determines what the suffixes are according to the number. The first item in the list is used for 1, the second for 2, and so on. If the century number is superior to the number of items in the list, the last one will be used instead. So, with the default configuration:
cty-ordinal-suffixes:
- rst
- nd
- rd
- th
the suffix of 7 will be “th”.
For language where the ordinal suffix depends on the last digit in the number, the field cty-number-part-for-ordinal-suffix
should be set to last-digit
(which is the default), so that you get “21rst” and not “21th”. Otherwise (e.g. in French), it should be set to whole
.
The suffix is printed in exponent
if it is the value of the field cty-ordinal-suffix-pos
. Default is normal
.
Naturally, the suffix is skipped if cty-numeral-type
is set to spelled-out
.
Formatting the unit
You can define the default value of ctyunit
by setting the cty-default-unit-form
metadata field.
cty-unit-sg
and cty-unit-pl
let you redefine the singular and plural forms of the unit. Since the unit begins immediately after the suffix, any space should be included. If it is a normal space, it should be encoded as the HTML entity  
, otherwise it will be stripped by Pandoc. This is why the default value for cty-unit-sg
is  century
.
Formatting the era
The only built-in era is the Christian era, which is the default value of cty-default-era
. You can define other eras thanks to the metadata field cty-other-eras
. It is composed of a list of structures made of the following fields:
name
: the name of the era;before-zero
: the value of the era for an explicitly negative century number;after-zero
: the value of the era for an explicitly positive century number;unspecified
: the value of the era for an unprefixed century number.
See the file test/test-french.md
for examples. Note that the values of the three last fields are subjected to the same constraints as with cty-unit-sg
and cty-unit-pl
.
Once a custom era has been set, you can call it via the ctyera
attribute:
cty-other-eras:
- name: hijra
before-zero: ''
after-zero: ' AH'
unspecified: ''
[2]{.cty ctyera=hijra}
2nd century AH
(In this example, we have set an empty string as the value of before-zero
because it is not customary to refer to centuries preceding the Hegira with this era.)
Changing the order
The field cty-parts-order
is a list composed of number
, suffix
, unit
and era
that determines the order in which the parts of the output are displayed. You can change this order if you need it.
Alphabetic list of recognized metadata fields
cty-default-era
: the name of a defined era (defaults tochristian
);cty-default-unit-form
: default value of attributectyunit
(defaults tosg
);cty-number-part-for-ordinal-suffix
: eitherwhole
orlast-digit
(defaults tolast-digit
);cty-numeral-style
: eitherlowercase
,uppercase
orsmallcaps
(defaults tolowercase
);cty-numeral-type
: eitherroman
,arabic
orspelled-out
(defaults toarabic
);cty-ordinal-suffix-pos
: eithernormal
orexponent
(defaults tonormal
);cty-ordinal-suffixes
: a list of strings;cty-other-eras
: a list of era definitions;cty-parts-order
: a list composed ofnumber
,suffix
,unit
andera
(which is the default order);cty-spelled-out-ordinals
: a list of strings enumerating the ordinal numbers;cty-unit-pl
: string (defaults to' centuries'
);cty-unit-sg
: string (defaults to' century'
);
License
All files in this repository and its sub-repositories are copyrighted by Bastien Dumont and distributed under the MIT license. See LICENSE.txt for more details.