Metadata declaration `@ …`

Metadata is data about data. Specifically, metadata is information about the actual content of a file or webpage. This can include various aspects such as the name of the author who wrote it, the language it is written in, a link to where one can subscribe to updates or technical instructions on how the content shall be styled.

In Aneamal, metadata is declared by assigning a metadata value to a metadata name. The Aneamal Translator recognizes a few dozen names. But you can also assign values to freely chosen names which essentially serve as variables. Metadata can be passed on to other files and can be inserted in the actual content.

How to

A metadata declaration is marked with a squirrel @ at the beginning of each line. The lines contain a metadata name and a value that is assigned to it. Values come in three flavors – text, links and embedded files – that are assigned in slightly different ways.

Metadata declarations can occur everywhere in a file. They are always processed before the file’s actual content. So even metadata declared at the end of a file can be used in a paragraph at its start.

Metadata can be declared in any Aneamal file. Additionally, the @meta.nml file is for centralized settings: its declarations are passed on to all Aneamal files in the same directory and all of its sub-directories that do not have an own @meta.nml file. @meta.nml files may only contain metadata declarations and other ghost markup.

Metadata names

Metadata names can be made of small and capital letters, digits, hyphens and the abundance of characters from outside the Basic Latin range of Unicode such as Hebrew letters, katakana syllables, umlauts and emojis.

Metadata names may neither contain whitespace nor any of the characters ! " # $ % & ' ( ) * + , . / : ; < = > ? @ [ ] ^ _ ` { | } ~ nor double backslashes \\.

Recognized names

Many metadata names serve special functions. For example, icon refers to an image file that is typically displayed in a browser’s address bar and in bookmarks next to the address or title of your webpage. robots metadata can ask web crawlers of search engines not to include your webpage in search results. See the catalog of recognized metadata names for a full list.

It is recommended to be frugal with recognized metadata declarations though. Use them when they are actually useful to you, not just because you can.

Reserved names

Metadata names which start with a small letter and consist only of small letters, digits and hyphens are reserved. They may get a special function in the future. You can use a reserved name though, if you precede it with a backslash \ in its declaration. Even if the name gets a special function later, your declaration will not trigger the newly recognized special function then. Example:

@ \copyright: All rights reserved.

Freely usable names

Metadata names that are neither recognized nor reserved can be used freely. That includes all names that start with a digit and all names that contain a capital letter or a character that is not from the Basic Latin Unicode range. Example declarations:

@ π: 3.1415926535…
@ 4: ->https://www.iucn.org/
@ IUCN: International Union for Conservation of Nature

Metadata values

Text value

Place a colon : between a metadata name and a single line of text to assign the latter to the former. Whitespace at the beginning or end of the assigned text is stripped. For example:

@ author: Nicolas Bourbaki

It is possible to break the single line of text onto multiple lines in your Aneamal file: place a backslash at the end of each but the last line and make sure that each line starts with a squirrel @. For instance, the following example is equivalent to the above example. Although broken onto two lines, it just encodes the single-line name Nicolas Bourbaki.

@ author: Nicolas \
@         Bourbaki

If your text contains an actual backslash, you need to precede that backslash with another backslash to mark it as literal.

Link value

A link always starts with an arrow -> composed of a hyphen and a greater-than sign, directly followed by the address of the link. You can enclose the address in backticks. Place a colon : and optionally space or tab characters between the metadata name and the link to assign the latter to the former. Here are a few examples:

 @ script: ->clock.js
 @ CS: ->https://www.quantamagazine.org/computer-science/
 @ WB: ->`https://web.archive.org/`

The first line in the example assigns a local JavaScript file to the recognized script metadata name. The second and third lines assign URLs to freely usable metadata names.

Embedded file as value

A few recognized metadata names accept an embedded file as value. Such a declaration consists of multiple lines. The first line contains just the metadata name after the squirrel @. Subsequent lines start with both a squirrel and a vertical bar | and otherwise contain the lines of the assigned embedded file. Here is an example with embedded HTML code:

@ htmlhead
@ |<!--
@ |Can you see
@ |what's going on
@ |in my head?
@ |-->

Inheritance

Metadata that has been declared in an @meta.nml file is automatically inherited by Aneamal files in the same directory or sub-directories without own @meta.nml file unless they explicitly opt out. Furthermore, @header.nml, @aside.nml, @footer.nml as well as linked and embedded files and quotation blocks inherit metadata from the containing file.

The following example uses metadata to store the meaning of acronyms from a European Space Agency mission. JUICE is declared in the main file, PRIDE in a quotation block therein. PRIDE will be available in the quotation block only, but JUICE will be available in both the main file and the quotation block, since the quotation block inherits metadata from the main file.

@ JUICE: Jupiter Icy Moons Explorer

> @ PRIDE: Planetary Radio Interferometer and Doppler Experiment
> …

But metadata is not just passed on by the file in which it is declared. Inherited metadata is also passed on. For instance, a quotation block inside an embedded file inside @aside.nml, which is implicitly integrated into a webpage alongside the main Aneamal file requested by a reader, could inherit metadata from all four Aneamal files that are further up in the chain:

@meta.nml
- the requested Aneamal file
  - @aside.nml
    - embedded file
      - quotation block

Overwriting inherited metadata

You can always overwrite inherited metadata. The next example has UN metadata declarations in both the main file and a quotation block. UN has the value United Nations in the main file. Although the quotation block inherits metadata, UN has the value Uranium mononitride there, since the declaration in the quotation block takes precedence inside it.

@ UN: United Nations

> @ UN: Uranium mononitride
> …

Fallback metadata

A fallback metadata declaration sets a default value which is only used, if no metadata of the same name gets inherited. So fallback metadata declarations do not overwrite inherited metadata. Turn a metadata declaration into a fallback declaration by adding a question mark ? immediately after the metadata name. For example, a @footer.nml file could contain the following declaration:

@ \copyright?: All rights reserved.

Metadata declaration @ …