[devhelp] help: have a separate topic page for the index-file-format

[Sébastien Wilmet <swilmet src gnome org>]

commit 4eaecb65edce8f561f993daae9004c63f8abb090
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Thu Dec 19 15:27:41 2019 +0100

    help: have a separate topic page for the index-file-format

 help/C/book-format.page       |  8 +----
 help/C/index-file-format.page | 68 +++++++++++++++++++++++++++++++++++++++++++
 help/meson.build              |  1 +
 3 files changed, 70 insertions(+), 7 deletions(-)
---
diff --git a/help/C/book-format.page b/help/C/book-format.page
index 0b4d8dd8..d93e6380 100644
--- a/help/C/book-format.page
+++ b/help/C/book-format.page
@@ -27,13 +27,7 @@
     HTML pages, plus possibly CSS files, images, etc;
   </p></item>
   <item><p>
-    A file with the <file>.devhelp2</file> file extension. It is the index
-    file, it contains the book structure plus a list of symbols (functions,
-    types, macros, signals, properties, …) that contains links to the HTML
-    files to reach those pages or symbols. In <app>Devhelp</app> the book
-    structure is shown in the side panel. And the
-    <link xref="search">search in the side panel</link> shows results found
-    in the index files.
+    An index file, see <link xref="index-file-format" /> for more information.
   </p></item>
 </list>
 <p>
diff --git a/help/C/index-file-format.page b/help/C/index-file-format.page
new file mode 100644
index 00000000..185d5312
--- /dev/null
+++ b/help/C/index-file-format.page
@@ -0,0 +1,68 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic"
+      id="index-file-format">
+
+<info>
+  <link type="guide" xref="index" />
+</info>
+
+<title>Index file format</title>
+
+<synopsis>
+  <p>
+    This page describes the purpose and the format of <file>*.devhelp2</file>
+    index files.
+  </p>
+</synopsis>
+
+<p>
+  A book (see <link xref="book-format" />) contains one index file. The index
+  file has the extension <file>.devhelp2</file> and has an XML format.
+</p>
+
+<note>
+  <p>
+    The “2” in the <file>*.devhelp2</file> file extension is because it is the
+    second version of the file format. The first version of the format, with
+    the <file>*.devhelp</file> file extension, is deprecated and its support in
+    <app>Devhelp</app> may be removed in the future. On application startup,
+    when <app>Devhelp</app> scans the filesystem to find books, it emits a
+    warning message in the terminal for each book that uses a deprecated
+    format.
+  </p>
+</note>
+
+<p>
+  The index file mainly contains:
+</p>
+<list>
+  <item><p>
+    The book structure (like a table of contents).
+  </p></item>
+  <item><p>
+    A list of symbols (functions, types, macros, signals, properties, …).
+  </p></item>
+</list>
+<p>
+  These contain links to the HTML files to reach the corresponding pages and
+  symbols.
+</p>
+<p>
+  In <app>Devhelp</app> the book structure is shown in the side panel. And the
+  <link xref="search">search in the side panel</link> shows results found in
+  the index files.
+</p>
+
+<section id="devhelp2-index-format">
+  <title>Specification of the <file>*.devhelp2</file> XML file format</title>
+  <p>
+    Unfortunately the <file>*.devhelp2</file> XML file format is not well
+    documented. There is still some hope that it will be fixed in the near
+    future. In the meantime, we recommend to look at what
+    <link xref="installing-api-documentation#gtk-doc">GTK-Doc</link> generates.
+    For the most precise definition of what <app>Devhelp</app> supports, read
+    the parser source code and the <app>Devhelp</app> API reference.
+  </p>
+</section>
+</page>
diff --git a/help/meson.build b/help/meson.build
index 6033d184..c9cd2f80 100644
--- a/help/meson.build
+++ b/help/meson.build
@@ -1,5 +1,6 @@
 pages = [
   'book-format.page',
+  'index-file-format.page',
   'index.page',
   'installing-api-documentation.page',
   'search.page'