Add documentation for RFC140 (#1039)

* Add documentation for RFC140

* Update terminology used in the RFC and set to adopted

Author: geographika

conf.py

@@ -408,7 +408,8 @@ class WKTLexer(RegexLexer):
             r'SMALL|SQUARE|TINY|TRIANGLE|TRUE|TRUETYPE|UC|UL|UNION|UR|UV_ANGLE|UV_MINUS_ANGLE|UV_LENGTH|UV_LENGTH_2|UVRASTER|VECTOR|'
             r'WFS|WMS|ALPHA|'
             r'GIF|JPEG|JPG|PNG|WBMP|SWF|PDF|GTIFF|PC256|RGB|RGBA|INT16|FLOAT32|GD|'
-            r'AGG|CAIRO|PNG8|SVG|KML|KMZ|GDAL|UTFGRID|MIXED'
+            r'AGG|CAIRO|PNG8|SVG|KML|KMZ|GDAL|UTFGRID|MIXED|'
+            r'MS_INDEX_TEMPLATE_DIRECTORY|TEST_MAPFILE'
             r')\b')
 
 keywords = (r'(ALIGN|'

en/development/rfc/ms-rfc-140.txt

@@ -1,44 +1,44 @@
 .. _rfc140:
 
 ================================================
-MS RFC 140: MapServer Homepage
+MS RFC 140: MapServer Index Page
 ================================================
 
 :Author: 	Seth Girvin
 :Contact: 	sethg@geographika.co.uk
-:Last Updated:  2025-05-09
+:Last Updated:  2025-17-10
 :Version: 	MapServer 8.6
-:Status: 	Draft
+:Status: 	Adopted
 
 1. Overview
 ===========
 
-This RFC proposes adding functionality to MapServer for dynamically generating a homepage that lists all map services available in a given deployment. 
+This RFC proposes adding functionality to MapServer for dynamically generating a index page that lists all map services available in a given deployment. 
 This feature would enable the creation of pages like https://maps.isric.org/ directly from a MapServer deployment, without requiring 
 additional scripting. While scripting can achieve this, integrating the capability into MapServer itself 
 would offer greater convenience and maintainability.
 
 With the introduction of the :ref:`CONFIG file <config>` in MapServer 8.0, it is now possible to centrally manage information about all Mapfiles in a deployment. 
-This would ensure that the homepage remains automatically synchronised with both the CONFIG file and the capabilities of the Mapfiles it references.
+This would ensure that the index page remains automatically synchronised with both the CONFIG file and the capabilities of the Mapfiles it references.
 
-The homepage would be a "superset" of all available Mapfiles in a MapServer deployment, as listed in the CONFIG file. 
-Each individual Mapfile would still have its own OGC API landing page, so the homepage is best described as a directory of all landing pages. 
+The index page would be a "superset" of all available Mapfiles in a MapServer deployment, as listed in the CONFIG file. 
+Each individual Mapfile would still have its own OGC API landing page, so the index page is best described as a directory of all landing pages. 
 
 As most MapServer deployments will likely be serving out a combination of WxS and new OGC API services for some time to come, 
 it will allow both types to be listed together.
 
 2.1 Proposed Solution
 =====================
 
-A new MapServer :ref:`CGI mode <cgi>` - ``mode=config`` will be added to allow details of the MapServer services to be returned. The ``MAPS`` block 
-in the :ref:`CONFIG file <config>` will be read to return a list of available services. By default the homepage service will be disabled unless a new
-``ENV`` option ``MS_HOMEPAGE_TEMPLATE`` has been set. This should be set to a folder containing a ``homepage.html`` value. However if only JSON
-responses are required it can be set to any value to enable the homepage service.
+New MapServer functionality will be added to allow details of the MapServer services to be returned. The ``MAPS`` block 
+in the :ref:`CONFIG file <config>` will be read to return a list of available services. By default the index page service will be disabled unless a new
+``ENV`` option ``MS_INDEX_TEMPLATE_DIRECTORY`` has been set. This should be set to a folder containing a ``landing.html`` value. However if only JSON
+responses are required it can be set to any value to enable the index page service.
 
 .. code-block:: mapfile
 
     ENV
-        MS_HOMEPAGE_TEMPLATE_DIRECTORY "share/ogcapi/templates/homepage/" # REQUIRED
+        MS_INDEX_TEMPLATE_DIRECTORY "/mapserver/share/ogcapi/templates/html-index-bootstrap/" # REQUIRED
         ...
     END
     # Example MAPS block in the CONFIG file
@@ -55,19 +55,19 @@ Requests will look as follows:
 .. code-block:: bat
 
     # example web requests
-    # http://localhost/cgi-bin/mapserv.exe?mode=config&f=json
-    # http://localhost/cgi-bin/mapserv.exe?mode=config&f=html
+    # http://localhost/cgi-bin/mapserv.exe?f=json
+    # http://localhost/cgi-bin/mapserv.exe?f=html
 
     # from the command line
-    mapserv -nh "QUERY_STRING=mode=config&f=json" -conf "/usr/local/etc/mapserver.conf"
-    mapserv -nh "QUERY_STRING=mode=config&f=html" -conf "C:\MapServer\apps\mapserver.conf"
+    mapserv -nh "QUERY_STRING=f=json" -conf "/usr/local/etc/mapserver.conf"
+    mapserv -nh "QUERY_STRING=f=html" -conf "C:\MapServer\apps\mapserver.conf"
 
 As the service returns JSON any client-side library can be used to render the output. However a default HTML template  will be provided
 following the same approach as in OGC Features API.
 
 .. note::
 
-    Even though the JSON format is based on the OGC API, the homepage JSON service will still be generated for a Mapfile even if it only supports
+    Even though the JSON format is based on the OGC API, the index page JSON service will still be generated for a Mapfile even if it only supports
     older WxS services.
 
 JSON Structure
@@ -104,7 +104,7 @@ https://demo.pygeoapi.io/api-catalog.json. An extract is shown below:
 
 The api-catalog specification allows for an additional ``service-meta`` property *"used to link to additional metadata about the API, 
 and is primarily intended for machine consumption."*  This can be used to add any additional properties from Mapfiles
-required to generate a MapServer homepage. ``service-doc`` isn't mandatory property, so WxS service links can ignore this. 
+required to generate a MapServer index page. ``service-doc`` isn't mandatory property, so WxS service links can ignore this. 
 
 An example of the proposed JSON and metadata is shown below:
 
@@ -181,7 +181,7 @@ that the URLs will return valid XML if the Mapfile is not configured correctly.
 
 This new feature will make services more discoverable, but with this comes the risk of leaking information.
 The service will be opt-in, and up to the administrators of the deployment if they want this information to be
-visible by setting the ``MS_HOMEPAGE_TEMPLATE_DIRECTORY`` value in the ``CONFIG`` file.
+visible by setting the ``MS_INDEX_TEMPLATE_DIRECTORY`` value in the ``CONFIG`` file.
 
 2.5 MapScript
 =============
@@ -194,12 +194,7 @@ None of the current MapServer ``mode`` functionality is supported in MapScript,
 
 This section contains notes from prototyping a possible solution. The final approach may differ. 
 
-A requests will be checked for ``mode=config`` in mapserv.c to return JSON and exit.
-A new mode will be added to ``mapservutil.c``
-
-.. code-block:: c
-
-    static char *const modeStrings[23]
+Requests will be checked in mapserv.c to return JSON and exit.
 
 To list services supported in a Mapfile ``msOWSRequestIsEnabled`` will be used:
 
@@ -219,16 +214,17 @@ if ``ows_onlineresource`` (or ``wms_``, ``wfs_`` etc.) is not set.
 + mapserv.c
 + mapservutil.c
 + mapserver.h
++ mapserv-config.cpp
 
 3.2 Ticket Reference
 --------------------
 
-+ TODO
++ https://github.com/MapServer/MapServer/pull/7350
 
 3.3 Documentation
 -----------------
 
-TODO
+See https://github.com/MapServer/MapServer-documentation/pull/1039
 
 4. Voting History
 =================

en/images/index-map-page.png

@@ -0,0 +1,168 @@
+.. index::
+   single: INDEX
+
+.. _index-page:
+
+*****************************************************************************
+ Index Page
+*****************************************************************************
+
+:Author:        Seth Girvin
+:Contact:       sethg at geographika.net
+:Last Updated:  2025-09-19
+
+
+Background
+==========
+
+MapServer 8.6 introduces an index page, proposed in :ref:`rfc140`. 
+This feature provides a single HTML page that lists all Mapfiles available in a deployment. 
+From this page, users can select an individual Mapfile to open a dedicated page containing useful links, 
+such as WMS capabilities documents and OGC Features API landing pages.
+
+In addition to the HTML pages, the same information is also available as JSON services, enabling programmatic access.
+
+The index pages are driven by the MapServer :ref:`config` file, and use the same template-based approach as the :ref:`OGC APIs <ogcapi>`.
+
+The index pages improves service discoverability for users and gives system administrators better visibility 
+into which services are exposed by their MapServer instances, making it easier to restrict or disable unneeded options.
+
+Configuration
+=============
+
+The index pages require a :ref:`config` file. MapServer uses this file to locate and list all Mapfiles available in the system.
+
+To activate the index pages, the config file needs to set a new ``MS_INDEX_TEMPLATE_DIRECTORY`` parameter. 
+This parameter specifies the folder containing the HTML templates used to render the index pages.
+
+.. code-block:: mapfile
+
+  CONFIG
+    ENV
+      MS_INDEX_TEMPLATE_DIRECTORY "/mapserver/share/ogcapi/templates/html-index-bootstrap/"
+    END
+
+MapServer provides two sets of templates, which may already be included with your deployment (depending on the package source). 
+If not, they are available in the MapServer repository under `share/ogcapi/templates <https://github.com/MapServer/MapServer/tree/main/share/ogcapi/templates>`__.
+
+- ``html-index-bootstrap`` - HTML templates styled using the Bootstrap framework.
+- ``html-index-plain`` - plain HTML templates with no styling.
+
+If your system will only be serving JSON output, the ``MS_INDEX_TEMPLATE_DIRECTORY`` value can be set to an empty string.
+
+.. code-block:: mapfile
+
+  CONFIG
+    ENV
+      MS_INDEX_TEMPLATE_DIRECTORY ""
+    END
+
+In this case JSON output remains accessible by appending ``?f=json`` to the request URL,
+but if you attempt to access the HTML output MapServer will return the following error.
+
+.. code-block:: json
+
+    {"code":"ConfigError","description":"Template directory not set."}
+
+If the configured template folder cannot be found, or if the account running MapServer does not have permission to read it, the following error will be returned:
+
+.. code-block:: json
+
+    {"code":"ConfigError","description":"InjaError error. [inja.exception.file_error] 
+    failed accessing file at 'C:\\Missing\\landing.html' (landing.html). (C:\\Missing\\)."}
+
+If ``MS_INDEX_TEMPLATE_DIRECTORY`` is not set, MapServer will behave as in previous versions and return standard messages when accessed without a query:
+
+.. code-block:: bat
+
+    loadParams(): Web application error. No query information to decode. QUERY_STRING is set, but empty.
+    mapserv(): Web application error. Traditional BROWSE mode requires a TEMPLATE in the WEB section, but none was provided.
+
+MapServer Homepage
+==================
+
+The homepage is available at the root of your MapServer deployment, for example:
+
+- http://localhost:8080/cgi-bin/mapserv.exe/
+- https://example.com/mapserver/
+- https://demo.mapserver.org/cgi-bin/mapserv/
+
+The page lists all Mapfiles defined in the :ref:`MAPS <mapfile-config-maps>` section of your ``CONFIG`` file.
+For each Mapfile, the page provides:
+
+- the map name
+- the number of layers
+- links to the Mapfile's individual index page (available in both HTML and JSON formats)
+
+.. image:: ../images/index-page.png
+
+If any Mapfiles referenced in the CONFIG file cannot be loaded, they will be displayed with an error message - "Error loading the map".
+In the JSON output, these Mapfiles will include a flag: ``"has-error":true``. This makes it possible to monitor the service programmatically and quickly identify problems with Mapfiles.
+
+The HTML output can be customized using the landing.html template file located in the configured template folder.
+
+Individual Mapfile Homepages
+============================
+
+When the index page functionality is enabled, each Mapfile listed in the :ref:`MAPS <mapfile-config-maps>` section of the config file
+has its own dedicated index page. 
+
+These pages can be accessed directly by appending the Mapfile's key to the MapServer URL.
+For example, the ``test.map`` referenced by the ``TEST_MAPFILE`` key in the configuration below can be accessed using URLs such as (keys are not case-sensitive):
+
+- http://localhost:8080/cgi-bin/mapserv.exe/TEST_MAPFILE/
+- https://example.com/mapserver/test_mapfile/
+- https://demo.mapserver.org/cgi-bin/mapserv/TEST_MAPFILE/
+
+.. code-block:: mapfile
+
+  CONFIG
+    ...
+    MAPS
+      TEST_MAPFILE "/opt/mapserver/test/test.map"
+
+Each Mapfile homepage lists the services enabled for that Mapfile. The following links may be available:
+
+- **CGI** - link to the inbuilt :ref:`openlayers`.
+
+  - Always available unless explicitly disabled via the ``ms_enable_modes`` setting in :ref:`mapfile-web-metadata`.
+
+- **OGC API** - links to the :ref:`OGC APIs <ogcapi>`.
+
+  - "OGC API Landing Page" (HTML)
+  - Root JSON service
+  - Available if MapServer was compiled with the ``-DWITH_OGCAPI`` option and one of the following :ref:`mapfile-web-metadata` settings is present:
+
+    - ``"oga_enable_request" "*"``
+    - ``"ows_enable_request" "*"``
+
+- **WMS** - links to the :ref:`WMS <wms_server>` GetCapabilities documents for supported versions:
+
+  - 1.0.0, 1.1.0, 1.1.1 and 1.3.0
+  - Available if MapServer was compiled with the ``-DUSE_WMS_SVR`` option, and one of the following :ref:`mapfile-web-metadata` settings:
+
+    - ``"wms_enable_request" "*"``
+    - ``"ows_enable_request" "*"``
+
+- **WFS** - links to the :ref:`WFS <wfs_server>` GetCapabilities documents for supported versions:
+
+  - 1.0.0, 1.1.0, and 2.0
+  - Available if MapServer was compiled with the ``-DUSE_WFS_SVR`` option, and one of the following :ref:`mapfile-web-metadata` settings:
+
+    - ``"wfs_enable_request" "*"``
+    - ``"ows_enable_request" "*"``
+
+- **WCS** - links to the :ref:`WCS <wcs_server>` GetCapabilities documents for supported versions:
+
+  - 1.0.0, 1.1.0, 2.0.0, and 2.0.1
+  - Available if MapServer was compiled with the ``-DUSE_WCS_SVR`` option, and one of the following :ref:`mapfile-web-metadata` settings:
+
+    - ``"wcs_enable_request" "*"``
+    - ``"ows_enable_request" "*"``
+
+.. image:: ../images/index-map-page.png
+
+The HTML output can be customized using the map.html template file located in the configured template folder.
+
+
+

en/images/index-page.png

@@ -16,11 +16,11 @@
    idw
    imagemaps
    kerneldensity
-   ogr_output   
+   ogr_output
    pdf
    svg
    tile_mode
    template_output
    kml_output
    utfgrid_output
-
+   index-page