From 6e43be662f3f086a1e2ddf5a35099506482d6724 Mon Sep 17 00:00:00 2001 From: Oliver Hamlet Date: Mon, 27 Jul 2020 22:20:34 +0100 Subject: [PATCH] Clarify GitHub Flavored Markdown strings in metadata docs --- docs/metadata/data_structures/cleaning.rst | 4 ++-- docs/metadata/data_structures/file.rst | 2 +- docs/metadata/data_structures/group.rst | 4 ++-- docs/metadata/data_structures/localised_content.rst | 2 +- docs/metadata/data_structures/message.rst | 12 ++---------- docs/metadata/introduction.rst | 4 ++++ 6 files changed, 12 insertions(+), 16 deletions(-) diff --git a/docs/metadata/data_structures/cleaning.rst b/docs/metadata/data_structures/cleaning.rst index cfa24069..d95a1bdb 100644 --- a/docs/metadata/data_structures/cleaning.rst +++ b/docs/metadata/data_structures/cleaning.rst @@ -13,13 +13,13 @@ This structure holds information on which versions of a plugin are dirty or clea ``string`` - **Required.** The utility that was used to check the plugin for dirty edits. If available, the version of the utility used should also be included (e.g. ``TES5Edit v3.11``). + **Required.** The utility that was used to check the plugin for dirty edits. If available, the version of the utility used should also be included (e.g. ``TES5Edit v3.11``). The string will be interpreted as GitHub Flavored Markdown. .. describe:: info ``string`` or ``localised content list`` - A message that will be displayed to the user. If a localised content list is provided, one of the structures must be for English. This is only used if the plugin is dirty, and is intended for providing cleaning instructions to the user. If undefined, defaults to an empty string. + A message that will be displayed to the user. If a string is provided, it will be interpreted as GitHub Flavored Markdown. If a localised content list is provided, one of the structures must be for English. This is only used if the plugin is dirty, and is intended for providing cleaning instructions to the user. If undefined, defaults to an empty string. .. describe:: itm diff --git a/docs/metadata/data_structures/file.rst b/docs/metadata/data_structures/file.rst index 30b9685a..c7bb4d6d 100644 --- a/docs/metadata/data_structures/file.rst +++ b/docs/metadata/data_structures/file.rst @@ -12,7 +12,7 @@ Map Form .. describe:: display - A substitute string to be displayed instead of the file path in any generated messages, eg. the name of the mod the file belongs to. If undefined, the ``name`` key's value is used. + A GitHub Flavored Markdown string, to be displayed instead of the file path in any generated messages, eg. the name of the mod the file belongs to. .. describe:: condition diff --git a/docs/metadata/data_structures/group.rst b/docs/metadata/data_structures/group.rst index 235b4189..1e5ac627 100644 --- a/docs/metadata/data_structures/group.rst +++ b/docs/metadata/data_structures/group.rst @@ -16,8 +16,8 @@ This structure can be used to hold group definitions. It is a key-value map. ``string`` - A description of the group, e.g. what sort of plugins it contains. If - undefined, the description is an empty string. + A GitHub Flavored Markdown description of the group, e.g. what sort of plugins + it contains. If undefined, the description is an empty string. .. describe:: after diff --git a/docs/metadata/data_structures/localised_content.rst b/docs/metadata/data_structures/localised_content.rst index f78238fc..8585f5be 100644 --- a/docs/metadata/data_structures/localised_content.rst +++ b/docs/metadata/data_structures/localised_content.rst @@ -5,7 +5,7 @@ The localised content data structure is a key-value string map. .. describe:: text - **Required.** The actual message content string. + **Required.** The GitHub Flavored Markdown message content string. .. describe:: lang diff --git a/docs/metadata/data_structures/message.rst b/docs/metadata/data_structures/message.rst index ed5aa861..3103e189 100644 --- a/docs/metadata/data_structures/message.rst +++ b/docs/metadata/data_structures/message.rst @@ -25,7 +25,7 @@ Messages are given as key-value maps. ``string`` or ``localised content list`` - **Required.** Either simply a string, or a list of localised content data structures. If the latter, one of the structures must be for English. + **Required.** Either simply a GitHub Flavored Markdown string, or a list of localised content data structures. If the latter, one of the structures must be for English. .. describe:: condition @@ -37,15 +37,7 @@ Messages are given as key-value maps. ``string list`` - A list of strings to be substituted into the message content string. The content string must use numbered specifiers (``%1%``, ``%2%``, etc.), where the numbers correspond to the position of the substitution string in this list to use, to denote where these strings are to be substituted. - -Message Formatting ------------------- - -LOOT supports formatting of messages using `GitHub Flavored Markdown`_. Support is provided by the `Marked`_ library (v0.3). Strings that get substituted into messages, such as file display names and cleaning data utility strings, also support the same formatting options. - -.. _GitHub Flavored Markdown: https://help.github.com/articles/github-flavored-markdown -.. _Marked: https://github.com/chjj/marked + A list of GitHub Flavored Markdown strings to be substituted into the message content string. The content string must use numbered specifiers (``%1%``, ``%2%``, etc.), where the numbers correspond to the position of the substitution string in this list to use, to denote where these strings are to be substituted. .. _languages: diff --git a/docs/metadata/introduction.rst b/docs/metadata/introduction.rst index d867ea56..35821f4f 100644 --- a/docs/metadata/introduction.rst +++ b/docs/metadata/introduction.rst @@ -17,3 +17,7 @@ An important point that is more specific to how LOOT uses YAML: * File paths cannot reference a path outside of the game's folder structure, ie. they cannot contain the substring ``../../``. In this document, where a value's type is given as ``X list`` this is equivalent to a YAML sequence of values which are of the data type ``X``. Where a value's type is given as ``X set``, this is equivalent to a YAML sequence of **unique** values which are of the data type ``X``. Uniqueness is determined using the equality criteria for that data type. All the non-standard data types that LOOT's metadata syntax uses have their equality criteria defined later in this document. + +Some strings are interpreted as `GitHub Flavored Markdown`_: where this is the case, the strings are interpreted according to version ``0.29-gfm`` of the specification. + +.. _GitHub Flavored Markdown: https://github.github.com/gfm/