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 3868405117c468480c0fe9d3c94ba789e16a1a8d..3d66a43c02a20c786db0ce61449fdcbbe425e74b 100644 (file)
--- 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 87324137254aa7eed0eb55c709d6dd6621480939..5956af7625a8a87641a416ffc87c2d844f191376 100644 (file)
--- 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.