From 8b9c4cfb87a9a35b4d7d26080fcad7def722dd02 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Sun, 24 Sep 2023 21:22:36 -0400
Subject: [PATCH] docs: Move the GMarkup SECTION

Move the content to the new markup.md file.

Helps: #3037
---
 docs/reference/glib/glib.toml.in |  1 +
 docs/reference/glib/markup.md    | 50 +++++++++++++++++++++++++++++
 docs/reference/glib/meson.build  |  1 +
 glib/gmarkup.c                   | 54 --------------------------------
 4 files changed, 52 insertions(+), 54 deletions(-)
 create mode 100644 docs/reference/glib/markup.md

diff --git a/docs/reference/glib/glib.toml.in b/docs/reference/glib/glib.toml.in
index 589d7d5f6..be79800fe 100644
--- a/docs/reference/glib/glib.toml.in
+++ b/docs/reference/glib/glib.toml.in
@@ -62,6 +62,7 @@ content_files = [
   "reference-counting.md",
   "testing.md",
   "threads.md",
+  "markup.md",
 ]
 content_images = [
   "file-name-encodings.png",
diff --git a/docs/reference/glib/markup.md b/docs/reference/glib/markup.md
new file mode 100644
index 000000000..edd3ec439
--- /dev/null
+++ b/docs/reference/glib/markup.md
@@ -0,0 +1,50 @@
+Title: Simple XML Subset Parser
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2011, 2014 Matthias Clasen
+SPDX-FileCopyrightText: 2012 David King
+
+# Simple XML Subset Parser
+
+The "GMarkup" parser is intended to parse a simple markup format
+that's a subset of XML. This is a small, efficient, easy-to-use
+parser. It should not be used if you expect to interoperate with
+other applications generating full-scale XML, and must not be used if you
+expect to parse untrusted input. However, it's very useful for application
+data files, config files, etc. where you know your application will be the
+only one writing the file.
+
+Full-scale XML parsers should be able to parse the subset used by
+GMarkup, so you can easily migrate to full-scale XML at a later
+time if the need arises.
+
+GMarkup is not guaranteed to signal an error on all invalid XML;
+the parser may accept documents that an XML parser would not.
+However, XML documents which are not well-formed (which is a
+weaker condition than being valid. See the
+[XML specification](http://www.w3.org/TR/REC-xml/)
+for definitions of these terms.) are not considered valid GMarkup
+documents.
+
+## Simplifications to XML
+
+The simplifications compared to full XML include:
+
+ - Only UTF-8 encoding is allowed
+ - No user-defined entities
+ - Processing instructions, comments and the doctype declaration
+   are "passed through" but are not interpreted in any way
+ - No DTD or validation
+
+The markup format does support:
+
+ - Elements
+ - Attributes
+ - 5 standard entities: `&amp;` `&lt;` `&gt;` `&quot;` `&apos;`
+ - Character references
+ - Sections marked as CDATA
+
+## An example parser
+
+Here is an example for a markup parser:
+[markup-example.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/glib/tests/markup-example.c)
+
diff --git a/docs/reference/glib/meson.build b/docs/reference/glib/meson.build
index 15ac741f7..ef315825d 100644
--- a/docs/reference/glib/meson.build
+++ b/docs/reference/glib/meson.build
@@ -160,6 +160,7 @@ expand_content_files = [
   'running.md',
   'testing.md',
   'threads.md',
+  'markup.md',
 ]
 
 glib_gir = meson.current_source_dir() / 'GLib-2.0.gir'
diff --git a/glib/gmarkup.c b/glib/gmarkup.c
index 9422abde4..6c07010db 100644
--- a/glib/gmarkup.c
+++ b/glib/gmarkup.c
@@ -38,60 +38,6 @@
 #include "glibintl.h"
 #include "gthread.h"
 
-/**
- * SECTION:markup
- * @Title: Simple XML Subset Parser
- * @Short_description: parses a subset of XML
- * @See_also: [XML Specification](http://www.w3.org/TR/REC-xml/)
- *
- * The "GMarkup" parser is intended to parse a simple markup format
- * that's a subset of XML. This is a small, efficient, easy-to-use
- * parser. It should not be used if you expect to interoperate with
- * other applications generating full-scale XML, and must not be used if you
- * expect to parse untrusted input. However, it's very
- * useful for application data files, config files, etc. where you
- * know your application will be the only one writing the file.
- * Full-scale XML parsers should be able to parse the subset used by
- * GMarkup, so you can easily migrate to full-scale XML at a later
- * time if the need arises.
- *
- * GMarkup is not guaranteed to signal an error on all invalid XML;
- * the parser may accept documents that an XML parser would not.
- * However, XML documents which are not well-formed (which is a
- * weaker condition than being valid. See the
- * [XML specification](http://www.w3.org/TR/REC-xml/)
- * for definitions of these terms.) are not considered valid GMarkup
- * documents.
- *
- * Simplifications to XML include:
- *
- * - Only UTF-8 encoding is allowed
- *
- * - No user-defined entities
- *
- * - Processing instructions, comments and the doctype declaration
- *   are "passed through" but are not interpreted in any way
- *
- * - No DTD or validation
- *
- * The markup format does support:
- *
- * - Elements
- *
- * - Attributes
- *
- * - 5 standard entities: &amp; &lt; &gt; &quot; &apos;
- *
- * - Character references
- *
- * - Sections marked as CDATA
-
- * ## An example parser # {#example}
- *
- * Here is an example for a markup parser:
- * [markup-example.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/glib/tests/markup-example.c)
- */
-
 G_DEFINE_QUARK (g-markup-error-quark, g_markup_error)
 
 typedef enum