lang-reference.md: fix lists formatting

1 files changed, 182 insertions, 179 deletions

diff --git a/docs/lang-reference.md b/docs/lang-reference.md
index 45487266..cd532abc 100644
--- a/docs/lang-reference.md
+++ b/docs/lang-reference.md
@@ -22,7 +22,7 @@ The preinstalled language files are located in
 `${PREFIX}/share/gtksourceview-${GSV_API_VERSION}/language-specs/`. Custom
 user languages are usually placed in
 `~/.local/share/gtksourceview-${GSV_API_VERSION}/language-specs/`. Note:
-replace ${GSV_API_VERSION} with 2.0 or 3.0 in the path for GtkSourceView version
+replace `${GSV_API_VERSION}` with 2.0 or 3.0 in the path for GtkSourceView version
 2 or version 3.
 
 ## Some advices
@@ -60,9 +60,9 @@ GtkSourceView.
 - LGPL v2.1+ license (copy/paste the license header from c.lang, for example).
 - Add the e-mail address of the language definition file author(s).
 - Refer to the HACKING file for submitting your language definition
-file upstream. If the file is not included upstream, you can also
-add the language definition file to the GtkSourceView wiki, so
-users can easily find it.
+  file upstream. If the file is not included upstream, you can also
+  add the language definition file to the GtkSourceView wiki, so
+  users can easily find it.
 
 ## Tag `<language>`
 
@@ -80,39 +80,39 @@ Contained elements:
 
 - `id` (mandatory)
 
-Identifier for the description. This is used for
-external references and must be unique among language descriptions. It can
-contain a string of letters, digits, hyphens ("`-`") and
-underscores ("`_`").
+  Identifier for the description. This is used for
+  external references and must be unique among language descriptions. It can
+  contain a string of letters, digits, hyphens ("`-`") and
+  underscores ("`_`").
 
 - `name` or `_name` (mandatory)
 
-The name of the language presented to the user. With `_name`, the
-string is marked for translation (see the gettext documentation).
+  The name of the language presented to the user. With `_name`, the
+  string is marked for translation (see the gettext documentation).
 
-The name should be marked for translation only if: (1) it contains a common
-English word, for example "C++ header" should be translated, but not "C++"
-or "XML". Or (2) if the name contains several words, because in some
-languages the word order should be different, for example "LLVM IR" or "RPM
-spec" should also be marked for translation.
+  The name should be marked for translation only if: (1) it contains a common
+  English word, for example "C++ header" should be translated, but not "C++"
+  or "XML". Or (2) if the name contains several words, because in some
+  languages the word order should be different, for example "LLVM IR" or "RPM
+  spec" should also be marked for translation.
 
 - `version` (mandatory)
 
-The version of the XML format (currently "2.0").
+  The version of the XML format (currently "2.0").
 
 - `section` or `_section` (optional)
 
-The category in which the language has to be grouped when presented to the user.
-With `_section` the string is marked for translation. Currently used
-categories in GtkSourceView are "Source", "Script", "Markup", "Scientific" and
-"Other", but it is possible to use arbitrary categories (while usually
-discouraged). The convention in GtkSourceView is to use `_section`.
+  The category in which the language has to be grouped when presented to the user.
+  With `_section` the string is marked for translation. Currently used
+  categories in GtkSourceView are "Source", "Script", "Markup", "Scientific" and
+  "Other", but it is possible to use arbitrary categories (while usually
+  discouraged). The convention in GtkSourceView is to use `_section`.
 
 - `hidden` (optional)
 
-It's a hint that the language should be "hidden" from user. For instance,
-def.lang has this flag, and a text editor should not present "default" as
-a syntax highlighting choice.
+  It's a hint that the language should be "hidden" from user. For instance,
+  def.lang has this flag, and a text editor should not present "default" as
+  a syntax highlighting choice.
 
 ## Tag `<metadata>`
 
@@ -122,33 +122,33 @@ Recognized elements are (all optional):
 
 - `mimetypes`
 
-The semicolon-separated list of mimetypes associated to the language. See the
-[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec/)
-freedesktop.org specification. A language definition file shipped by
-GtkSourceView needs to have a mimetype defined in the shared-mime-info
-database. If the language definition file is not shipped by GtkSourceView, you
-can also create the mimetype locally, usually in
-`~/.local/share/mime/packages/`.
+  The semicolon-separated list of mimetypes associated to the language. See the
+  [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec/)
+  freedesktop.org specification. A language definition file shipped by
+  GtkSourceView needs to have a mimetype defined in the shared-mime-info
+  database. If the language definition file is not shipped by GtkSourceView, you
+  can also create the mimetype locally, usually in
+  `~/.local/share/mime/packages/`.
 
 - `globs`
 
-The semicolon-separated list of globs associated to the language.
+  The semicolon-separated list of globs associated to the language.
 
 - `line-comment-start`
 
-String used to create single-line comment in files of this type, e.g.
-"#" in shell scripts.
-It may be used in an editor to implement Comment/Uncomment functionality.
+  String used to create single-line comment in files of this type, e.g.
+  "#" in shell scripts.
+  It may be used in an editor to implement Comment/Uncomment functionality.
 
 - `block-comment-start`
 
-String used to start block comment in files of this type, e.g. "/*" in C
-files.
+  String used to start block comment in files of this type, e.g. "/*" in C
+  files.
 
 - `block-comment-end`
 
-String used to end block comment in files of this type, e.g. "*/" in C
-files.
+  String used to end block comment in files of this type, e.g. "*/" in C
+  files.
 
 ## Tag `<styles>`
 
@@ -166,37 +166,37 @@ Contained elements: none.
 
 ### Attributes
 
--`id` (mandatory)
-
-Identifier for the style. This is used in the current language
-to refer to this style and must be unique for the current document.
-It can contain a string of letters, digits,
-hyphens ("`-`") and underscores ("`_`").
-
--`name` or `_name` (mandatory)
-
-The user visible name for the style. With `_name` the string is
-marked for translation.
-  
-The convention in GtkSourceView is to **never** mark those
-strings for translation because they are extremely rarely used in the UI of
-an application (for example it could be used by a GUI tool to edit or create
-style schemes, but it is not really useful beyond that), and because those
-strings would be hard to translate (as a result, if those strings are
-translated, in practice they would often be translated in a way that the
-user doesn't understand what it means; for example for the C language,
-"include" or "define" should not be translated, those are keywords of the
-programming language).
-
--`map-to` (optional)
-
-Used to map the style with a default style, to use colors and
-font properties defined for those default styles.
-The id of the default style has to be preceded with the id of the
-language where it is defined, separated with a semicolon ":".
-When omitted the style is not considered derived from any style and will
-not be highlighted until the user specifies a color scheme for this
-style.
+- `id` (mandatory)
+
+  Identifier for the style. This is used in the current language
+  to refer to this style and must be unique for the current document.
+  It can contain a string of letters, digits,
+  hyphens ("`-`") and underscores ("`_`").
+
+- `name` or `_name` (mandatory)
+
+  The user visible name for the style. With `_name` the string is
+  marked for translation.
+
+  The convention in GtkSourceView is to **never** mark those
+  strings for translation because they are extremely rarely used in the UI of
+  an application (for example it could be used by a GUI tool to edit or create
+  style schemes, but it is not really useful beyond that), and because those
+  strings would be hard to translate (as a result, if those strings are
+  translated, in practice they would often be translated in a way that the
+  user doesn't understand what it means; for example for the C language,
+  "include" or "define" should not be translated, those are keywords of the
+  programming language).
+
+- `map-to` (optional)
+
+  Used to map the style with a default style, to use colors and
+  font properties defined for those default styles.
+  The id of the default style has to be preceded with the id of the
+  language where it is defined, separated with a semicolon ":".
+  When omitted the style is not considered derived from any style and will
+  not be highlighted until the user specifies a color scheme for this
+  style.
 
 ## Tag `<keyword-char-class>`
 
@@ -215,24 +215,24 @@ Contained elements: none.
 
 ### Attributes
 
--`case-sensitive` (optional)
+- `case-sensitive` (optional)
 
-Set to `false` to make regular expressions ignore case.
-Defaults to `true`.
+  Set to `false` to make regular expressions ignore case.
+  Defaults to `true`.
 
--`extended` (optional)
+- `extended` (optional)
 
-Setting this to `true` makes the regular
-expression engine ignore spaces and comments. These comments start with
-"`#`" and continue to the end of the line.
-Defaults to `false`.
+  Setting this to `true` makes the regular
+  expression engine ignore spaces and comments. These comments start with
+  "`#`" and continue to the end of the line.
+  Defaults to `false`.
 
--`dupnames` (optional)
+- `dupnames` (optional)
 
-Setting this to true allows one to repeat an identifier
-for capturing parentheses.  This is useful for some patterns that you
-know only one instance of a named subpattern can ever be matched.
-Defaults to `false`.
+  Setting this to true allows one to repeat an identifier
+  for capturing parentheses.  This is useful for some patterns that you
+  know only one instance of a named subpattern can ever be matched.
+  Defaults to `false`.
 
 ## Tag `<definitions>`
 
@@ -255,7 +255,8 @@ Contained elements:
 ## Tag `<define-regex>`
 
 The syntax highlighting engine of GtkSourceView uses [struct@GLib.Regex],
-which uses the PCRE library. See the [Regular expression syntax](https://developer.gnome.org/glib/stable/glib-regex-syntax.html)
+which uses the PCRE library. See the
+[Regular expression syntax](https://developer-old.gnome.org/glib/stable/glib-regex-syntax.html)
 page in the GLib reference manual.
 
 The `<define-regex>` tag defines a regular expression that can
@@ -270,10 +271,10 @@ element. To disable a group of options, instead, you have to prepend an hyphen
 the standard Perl style regular expressions:
 
 - `\%[` and `\%]` are custom word boundaries, which can
-be redefined with the `<keyword-char-class>` (in contrast with `\b`);
+  be redefined with the `<keyword-char-class>` (in contrast with `\b`);
 
 - `\%{id}` will include the regular expression defined in another
-`<define-regex>` element with the specified id.
+  `<define-regex>` element with the specified id.
 
 It is allowed to use any of the attributes from `<default-regex-options>` as attributes of this tag.
 
@@ -283,10 +284,10 @@ Contained elements: none.
 
 - `id` (mandatory)
 
-Identifier for the regular expression. This is used
-for the inclusion of the defined regular expression and must be unique
-for the current document. It can contain a string of letters, digits,
-hyphens ("`-`") and underscores ("`_`").
+  Identifier for the regular expression. This is used
+  for the inclusion of the defined regular expression and must be unique
+  for the current document. It can contain a string of letters, digits,
+  hyphens ("`-`") and underscores ("`_`").
 
 ## Tag `<context>`
 
@@ -323,45 +324,45 @@ Contained elements:
 
 - `id` (optional)
 
-A unique identifier for the context, used in references to the context. It
-can contain a string of letters, digits, hyphens ("`-`") and
-underscores ("`_`").
+  A unique identifier for the context, used in references to the context. It
+  can contain a string of letters, digits, hyphens ("`-`") and
+  underscores ("`_`").
 
 - `style-ref` (optional)
 
-Highlighting style for this context. Value of this attribute
-may be id of a style defined in current lang file, or id of a style
-defined in other files prefixed with corresponding language id,
-e.g. "def:comment".
+  Highlighting style for this context. Value of this attribute
+  may be id of a style defined in current lang file, or id of a style
+  defined in other files prefixed with corresponding language id,
+  e.g. "def:comment".
 
 - `extend-parent` (optional)
 
-A boolean value telling the engine whether the context has higher
-priority than the end of its parent. If not specified it defaults to
-`true`.
+  A boolean value telling the engine whether the context has higher
+  priority than the end of its parent. If not specified it defaults to
+  `true`.
 
-`end-parent` (optional)
+- `end-parent` (optional)
 
-A boolean value telling the engine whether the context terminates parent context.
-If not specified it defaults to `false`.
+  A boolean value telling the engine whether the context terminates parent context.
+  If not specified it defaults to `false`.
 
 - `first-line-only` (optional)
 
-A boolean value telling the engine whether the context can occur only
-on the first line of buffer. If not specified it defaults to `false`.
+  A boolean value telling the engine whether the context can occur only
+  on the first line of buffer. If not specified it defaults to `false`.
 
 - `once-only` (optional)
 
-A boolean value telling the engine whether the context can occur only
-once in its parent. If not specified it defaults to `false`.
+  A boolean value telling the engine whether the context can occur only
+  once in its parent. If not specified it defaults to `false`.
 
 - `class` (optional)
 
-A space-separated list of context classes to enable.
+  A space-separated list of context classes to enable.
 
 - `class-disabled` (optional)
 
-A space-separated list of context classes to disable.
+  A space-separated list of context classes to disable.
 
 ## Container contexts
 
@@ -383,62 +384,62 @@ Contained elements:
 
 ### Attributes
 
--`id` (mandatory only if `<start>` not present)
+- `id` (mandatory only if `<start>` not present)
 
-A unique identifier for the context, used in references to the context. It
-can contain a string of letters, digits, hyphens ("`-`") and
-underscores ("`_`").
+  A unique identifier for the context, used in references to the context. It
+  can contain a string of letters, digits, hyphens ("`-`") and
+  underscores ("`_`").
 
--`style-ref` (optional)
+- `style-ref` (optional)
 
-Highlighting style for this context. Value of this attribute
-may be id of a style defined in current lang file, or id of a style
-defined in other files prefixed with corresponding language id,
-e.g. "def:comment".
+  Highlighting style for this context. Value of this attribute
+  may be id of a style defined in current lang file, or id of a style
+  defined in other files prefixed with corresponding language id,
+  e.g. "def:comment".
 
--`style-inside` (optional)
+- `style-inside` (optional)
 
-If this attribute is "true", then the highlighting style will
-be applied to the area between start and end matches; otherwise
-whole context will be highlighted.
+  If this attribute is "true", then the highlighting style will
+  be applied to the area between start and end matches; otherwise
+  whole context will be highlighted.
 
--`extend-parent` (optional)
+- `extend-parent` (optional)
 
-A boolean value telling the engine whether the context has a higher
-priority than the end of its parent. If not specified it defaults to
-`true`.
+  A boolean value telling the engine whether the context has a higher
+  priority than the end of its parent. If not specified it defaults to
+  `true`.
 
--`end-at-line-end` (optional)
+- `end-at-line-end` (optional)
 
-A boolean value telling the engine whether the context must be forced
-to end at the end of the line. If not specified it defaults to
-`false`.
+  A boolean value telling the engine whether the context must be forced
+  to end at the end of the line. If not specified it defaults to
+  `false`.
 
--`end-parent` (optional)
+- `end-parent` (optional)
 
-A boolean value telling the engine whether the context terminates parent context
-when it ends.
-If not specified it defaults to `false`.
+  A boolean value telling the engine whether the context terminates parent context
+  when it ends.
+  If not specified it defaults to `false`.
 
--`first-line-only` (optional)
+- `first-line-only` (optional)
 
 A boolean value telling the engine whether the context can start only
 on the first line of buffer. If not specified it defaults to `false`.
 
--`once-only` (optional)
+- `once-only` (optional)
 
-A boolean value telling the engine whether the context can occur only
-once in its parent. For a container context, it means that
-**each** included context can occur once.
-If not specified it defaults to `false`.
+  A boolean value telling the engine whether the context can occur only
+  once in its parent. For a container context, it means that
+  **each** included context can occur once.
+  If not specified it defaults to `false`.
 
--`class` (optional)
+- `class` (optional)
 
-A space-separated list of context classes to enable.
+  A space-separated list of context classes to enable.
 
--`class-disabled` (optional)
+- `class-disabled` (optional)
 
-A space-separated list of context classes to disable.
+  A space-separated list of context classes to disable.
 
 ## Sub-pattern contexts
 
@@ -450,32 +451,32 @@ Contained elements: none.
 
 ### Attributes
 
--`id` (optional)
+- `id` (optional)
 
-A unique identifier for the context. It can contain a string of letters,
-digits, hyphens ("`-`") and underscores ("`_`").
+  A unique identifier for the context. It can contain a string of letters,
+  digits, hyphens ("`-`") and underscores ("`_`").
 
--`sub-pattern` (mandatory)
+- `sub-pattern` (mandatory)
 
-The sub-pattern to which we refer. "0" means the whole expression, "1" the
-first group, "2" the second one, etc. If named sub-patterns are used you can
-also use the name.
+  The sub-pattern to which we refer. "0" means the whole expression, "1" the
+  first group, "2" the second one, etc. If named sub-patterns are used you can
+  also use the name.
 
--`where` (mandatory only in container contexts)
+- `where` (mandatory only in container contexts)
 
-Can be "`start`" or "`end`". It has to be used
-only if the parent is a container context to specify whether the
-sub-pattern is in the regular
-expression of the `<start>` or the `<end>`
-element. In simple contexts it must be omitted.
+  Can be "`start`" or "`end`". It has to be used
+  only if the parent is a container context to specify whether the
+  sub-pattern is in the regular
+  expression of the `<start>` or the `<end>`
+  element. In simple contexts it must be omitted.
 
--`class` (optional)
+- `class` (optional)
 
-A space-separated list of context classes to enable.
+  A space-separated list of context classes to enable.
 
--`class-disabled` (optional)
+- `class-disabled` (optional)
 
-A space-separated list of context classes to disable.
+  A space-separated list of context classes to disable.
 
 ## Reference contexts
 
@@ -487,28 +488,28 @@ Contained elements: none.
 
 - `ref` (mandatory)
 
-The id of the context to be included. A colon followed by an asterisk
-("`:*`") at the end of the id means that the parent should include
-every children of the specified context, instead of the context itself.
-Prepending the id of another language to the id of the context (separated
-with a semicolon ":") is possible to include contexts defined inside such
-external language.
+  The id of the context to be included. A colon followed by an asterisk
+  ("`:*`") at the end of the id means that the parent should include
+  every children of the specified context, instead of the context itself.
+  Prepending the id of another language to the id of the context (separated
+  with a semicolon ":") is possible to include contexts defined inside such
+  external language.
 
 - `style-ref` (optional)
 
-Style in included context may be overridden by using this attribute.
-Its value is id of the style to be used instead of style specified
-in the referenced context.
+  Style in included context may be overridden by using this attribute.
+  Its value is id of the style to be used instead of style specified
+  in the referenced context.
 
 - `ignore-style` (optional)
 
-If this attribute is "true" then the referenced context will not
-be highlighted. It does not affect child contexts and their styles.
+  If this attribute is "true" then the referenced context will not
+  be highlighted. It does not affect child contexts and their styles.
 
--`original` (optional)
+- `original` (optional)
 
-If this attribute is "true", it references the original context, if it
-has been replaced with the `<replace>` tag.
+  If this attribute is "true", it references the original context, if it
+  has been replaced with the `<replace>` tag.
 
 ## Keyword contexts
 
@@ -576,7 +577,8 @@ implement shell-style here-documents with this code:
 </context>
 ```
 
-It is also possible to use any of the attributes from `<default-regex-options>` as attributes of this tag.
+It is also possible to use any of the attributes from
+`<default-regex-options>` as attributes of this tag.
 
 Contained elements: none.
 
@@ -609,7 +611,8 @@ The replace tag allows you to change one context so it functions as
 another context.  For example, in the `html.lang` definition,
 there are a few references to a null context with id
 "`embedded-lang-hook`".  In `php.lang`, that context is
-replaced like this: `<replace id="html:embedded-lang-hook" ref="php-block">`, so that php blocks are recognized within the
+replaced like this: `<replace id="html:embedded-lang-hook" ref="php-block">`,
+so that php blocks are recognized within the
 `html:html` context at the points where the
 `embedded-lang-hook` context appears.
 
@@ -619,8 +622,8 @@ Contained elements: none.
 
 - `id` (mandatory)
 
-The id of the context to replace. Ex: `id="html:embedded-lang-hook"`
+  The id of the context to replace. Ex: `id="html:embedded-lang-hook"`
 
 - `ref` (mandatory)
 
-The id of the context to put in place of the context being replaced. Ex: `ref="php-block"`
+  The id of the context to put in place of the context being replaced. Ex: `ref="php-block"`