Dear all,
I have added a first prototype of a generated configuration parameter reference
page for NaviServer 5.1:
https://naviserver.sourceforge.io/5.1/manual/files/admin-config-params.html
The page addresses a long standing issue that the parameter documentation is
scattered and sometimes incomplete or no inconsistent. The page is generated
from a machine-readable Tcl dict containing configuration metadata such as
parameter names, types, defaults, allowed values, short descriptions,
deprecation notes, and section/module descriptions. The generation approach
should reduce maintenance work for parameter documentation in the future. The
documentation generator spits out include files, that can be as well used in
other man pages.
The same dict is also used by the nsstats module to provide online help: on the
page showing the current configuration database, known parameters now get
tooltips explaining their meaning, type, default value, and deprecation status
where applicable.
The current prototype covers the most important sections from the sample
configuration, including global sections, network drivers, per-server sections,
and several server modules. The structure is still evolving, but the approach
should help us avoid scattering configuration descriptions across C code,
sample configs, and manual pages.
The page show several shortcomings in the structuring of current parameters.
For the time being, i have omitted there the 11 global parameters “smtp*”,
which are there for a single command which is probably barely used
(ns_sendmail) , since there are many more powerful options available. one
should at least put it into an own section (like e.g. ns/fastpath) and marl the
old names deprecated. Also the ns/param/log* parameter would deserve an own
section.
Feedback is welcome, especially on unclear descriptions or better
wording/examples/... for the generated reference. Or about other things, you
would like to see in this documentation.
All the best
-g
_______________________________________________
naviserver-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/naviserver-devel
