From: Alan T. DeKok <aland@freeradius.org>
Date: Mon, 3 Jun 2024 15:37:40 +0000 (-0400)
Subject: rearrange to put reference docs at the start
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=61530009ef8bcb89b7cbc6696a5dbeec11dd4db9;p=thirdparty%2Ffreeradius-server.git

rearrange to put reference docs at the start

and add some text in the main reference page
---

diff --git a/doc/antora/antora.yml b/doc/antora/antora.yml
index 3868405117c..3d66a43c02a 100644
--- a/doc/antora/antora.yml
+++ b/doc/antora/antora.yml
@@ -10,10 +10,10 @@ prerelease: Devel
 start_page: ROOT:index.adoc
 nav:
 - modules/ROOT/nav.adoc
+- modules/reference/nav.adoc
+- modules/raddb/nav.adoc
 - modules/installation/nav.adoc
 - modules/concepts/nav.adoc
 - modules/howto/nav.adoc
 - modules/tutorials/nav.adoc
-- modules/reference/nav.adoc
 - modules/developers/nav.adoc
-- modules/raddb/nav.adoc
diff --git a/doc/antora/modules/reference/pages/index.adoc b/doc/antora/modules/reference/pages/index.adoc
index 87324137254..5956af7625a 100644
--- a/doc/antora/modules/reference/pages/index.adoc
+++ b/doc/antora/modules/reference/pages/index.adoc
@@ -1,8 +1,33 @@
 = Reference Documentation
 
-We have a lot of stuff
+There are small number of high-level concepts associated with the server, as outlined below.
 
+* xref:unlang/index.adoc[Unlang] syntax
+* xref:raddb:index.html[Configuration Files]
 * xref:dictionary/index.adoc[Dictionary] where attribute names and data types are defined
 * xref:type/index.adoc[Data Types] in the server
-* xref:unlang/index.adoc[Unlang] syntax
 * xref:xlat/index.adoc[Dynamic expansions] i.e. "xlat"s.
+
+The server includes a large number of
+xref:raddb:index.html[configuration files].  These files are
+automatically converted to HTML for the on-line documentation.
+
+During normal operation, the server receives packets of information
+from the network.  Data in the packets is usually encoded in
+pre-defined "attributes" (RADIUS), or "options" (DHCP).  The
+definitions are loaded from xref:dictionary/index.adoc[dictionary]
+files.
+
+These definitions are strongly typed.  That is, each attribute has a
+pre-defined xref:type/index.adoc[data type].  For example, an
+attribute "Framed-IP-Address" has data type xref:type/ip.adoc[ipaddr].
+
+Packets are processed via the xref:unlang/index.adoc[Unlang] policy
+language.  Policies allow the server to read information in databases,
+perform if / then / else checks, add content to replies, along with
+many other actions.
+
+When processing packets, it is possible to call functions or do string
+manipulation with attribute contents.  The
+xref:xlat/index.adoc[dynamic expansion] documentation describes how
+this is done.