pandoc-lua-filters/centuries/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 to christian);
• cty-default-unit-form: default value of attribute ctyunit (defaults to sg);
• cty-number-part-for-ordinal-suffix: either whole or last-digit (defaults to last-digit);
• cty-numeral-style: either lowercase, uppercase or smallcaps (defaults to lowercase);
• cty-numeral-type: either roman, arabic or spelled-out (defaults to arabic);
• cty-ordinal-suffix-pos: either normal or exponent (defaults to normal);
• cty-ordinal-suffixes: a list of strings;
• cty-other-eras: a list of era definitions;
• cty-parts-order: a list composed of number, suffix, unit and era (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.