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.

``` md
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.

``` md
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](#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:

``` yaml
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`](#formatting-the-unit).

Once a custom era has been set, you can call it via the `ctyera` attribute:

``` yaml
cty-other-eras:
- name: hijra
  before-zero: ''
  after-zero: ' AH'
  unspecified: ''
```

``` md
[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.