Emacs Docs

Appearance

The denote-link-description-format to format link descriptions ​

The user option denote-link-description-format controls how the command denote-link and related functions create a link description by default.

The value can be either a function or a string. If it is a function, it is called with two argument, the file and file type, and should return a string representing the link description. The default is a function that returns the active region or the title of the note (with the signature if present).

For backward compatibility, the function can also take a single parameter, the given file. In that case, it is responsible for figuring out the file type in order to return the correct description.

If the value is a string, it treats specially the following specifiers:

  • The ‘%t’ is the Denote ‘TITLE’ in the front matter or the file name.
  • The ‘%T’ is the Denote ‘TITLE’ in the file name.
  • The ‘%i’ is the Denote ‘IDENTIFIER’ of the file.
  • The ‘%I’ is the identifier converted to ‘DAYNAME, DAYNUM MONTHNUM YEAR’.
  • The ‘%d’ is the same as ‘%i’ (‘DATE’ mnemonic).
  • The ‘%D’ is a “do what I mean” which behaves the same as ‘%t’ and if that returns nothing, it falls back to ‘%I’, then ‘%i’.
  • The ‘%d’ is the same as ‘%i’ (‘DATE’ mnemonic).
  • The ‘%s’ is the Denote ‘SIGNATURE’ of the file.
  • The ‘%k’ is the Denote ‘KEYWORDS’ of the file.
  • The ‘%%’ is a literal percent sign.

In addition, the following flags are available for each of the specifiers:

0 ​

Pad to the width, if given, with zeros instead of spaces.

- ​

Pad to the width, if given, on the right instead of the left.

< ​

Truncate to the width and precision, if given, on the left.

> ​

Truncate to the width and precision, if given, on the right.

^ ​

Convert to upper case.

_ ​

Convert to lower case.

When combined all together, the above are written thus:

%<flags><width><precision>SPECIFIER-CHARACTER

Any other text in the string it taken as-is. Users may want, for example, to include some text that makes Denote links stand out, such as a ‘[D]’ prefix.

If the region is active, its text is used as the link’s description.