[COMMITTED] doc: generate settings documentation from poke

[Jose E. Marchesi]

The poke settings registry contains the on-line documentation for all
the global settings supported by the tool.

In order to not replicate the same contents in the user manual, this
patch adds a little poke program that dumps the documentation in
Texinfo format.  The manual then @includes this content at the right
section.

2022-01-17  Jose E. Marchesi  <jemarch@gnu.org>

        * doc/settings-to-texi.pk: New file.
        * doc/Makefile.am (poke_TEXINFOS): Add poke-settings.texi.
        (poke-settings.texi): Rule to enerate poke-settings.texi.
        (MAINTAINERCLEANFILES): Add poke-settings.texi.
        (EXTRA_DIST): Likewise.
        * doc/poke.texi (set command): Include poke-settings.texi.
---
 ChangeLog               |  9 +++++++++
 doc/Makefile.am         | 15 ++++++++++++---
 doc/poke.texi           | 49 ++-----------------------------------------------
 doc/settings-to-texi.pk | 42 ++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 65 insertions(+), 50 deletions(-)
 create mode 100644 doc/settings-to-texi.pk

diff --git a/ChangeLog b/ChangeLog
index a958d603..444457a7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,14 @@
 2022-01-17  Jose E. Marchesi  <jemarch@gnu.org>
 
+       * doc/settings-to-texi.pk: New file.
+       * doc/Makefile.am (poke_TEXINFOS): Add poke-settings.texi.
+       (poke-settings.texi): Rule to enerate poke-settings.texi.
+       (MAINTAINERCLEANFILES): Add poke-settings.texi.
+       (EXTRA_DIST): Likewise.
+       * doc/poke.texi (set command): Include poke-settings.texi.
+
+2022-01-17  Jose E. Marchesi  <jemarch@gnu.org>
+
        * poke/pk-settings.pk (pk_settings_dump): Avoid allocating a
        local.
        Reorder setting entries.
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 85c7d3bd..92dd8f6c 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -14,9 +14,10 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 info_TEXINFOS = poke.texi
-poke_TEXINFOS = fdl.texi pvm-insns.texi
+poke_TEXINFOS = fdl.texi pvm-insns.texi poke-settings.texi
 
-EXTRA_DIST = gen-pvm-insns.sh learn-poke-language-in-y-minutes.pk
+EXTRA_DIST = gen-pvm-insns.sh learn-poke-language-in-y-minutes.pk \
+             settings-to-texi.pk
 
 # The description of PVM instructions is generated from the
 # libpoke/pvm.jitter file.
@@ -25,6 +26,14 @@ pvm-insns.texi: $(top_srcdir)/libpoke/pvm.jitter 
$(srcdir)/gen-pvm-insns.sh
        $(srcdir)/gen-pvm-insns.sh $(top_srcdir)/libpoke/pvm.jitter \
          > pvm-insns.texi
 
+# The documentation for poke settings is generated by poke itself.
+# This is to avoid replication.  The documentation of the settings
+# lives in poke/pk-settings.pk.
+
+poke-settings.texi: $(srcdir)/settings-to-texi.pk 
$(top_srcdir)/poke/pk-settings.pk
+       $(top_builddir)/run poke -L $(srcdir)/settings-to-texi.pk \
+          > poke-settings.texi
+
 # This rule generates a list of the node names from the manual.
 # It then substitutes spaces with '/' which is a kludge used to
 # work around some limitations of readline.
@@ -73,4 +82,4 @@ poke.text: $(srcdir)/poke.texi
 MOSTLYCLEANFILES = \
   nodelist \
   poke.txmp
-MAINTAINERCLEANFILES = pvm-insns.texi poke.text
+MAINTAINERCLEANFILES = pvm-insns.texi poke-settings.texi poke.text
diff --git a/doc/poke.texi b/doc/poke.texi
index 1260112b..2382016e 100644
--- a/doc/poke.texi
+++ b/doc/poke.texi
@@ -8237,55 +8237,10 @@ Prints the value of the given @var{setting}.
 Sets the value of @var{setting} to @var{value}.
 @end table
 
+@noindent
 The following settings can be handled with @command{.set}:
 
-@table @code
-@item endian
-@cindex endianness
-Byte endianness that will be used when mapping the IO space.  Valid
-values are @code{big}, @code{little} and @code{host}.  The default
-endianness is big endian.
-@item obase
-@cindex base, of displayed values
-Numeric base to be used when displaying values in the REPL and in
-@code{printf} statements using the @code{%v} format tag.  Valid values
-are @code{2}, @code{8}, @code{10} and @code{16}.  Default value is
-@code{10}.
-@item pretty-print
-@cindex pretty printing
-Flag indicating whether pretty-printers shall be used when printing
-values in the REPL and in @code{printf} statements using the @code{%v}
-format tag.  Valid values are @code{yes} and @code{no}.  Default value
-is @code{no}.
-@item error-on-warning
-@cindex errors
-@cindex warnings
-Flag indicating whether handling compilation warnings as errors.
-Default value is @code{no}.
-@item omode
-@cindex mode, of displayed values
-It defines the way the binary struct data is displayed. In @code{flat} mode
-data is not formatted in any special way. In @code{tree} mode the struct data
-is displayed in a hierarchical (tree) mode.
-@item odepth
-@cindex depth, of displayed struct fields
-In @code{tree} and @code{flat} mode the struct fields are recursively displayed
-up to the @code{depth}-th level. The default value @code{0} means no limit.
-@item oindent
-@cindex indent, as number of spaces
-Number defining the number of spaces used for indentation for each level. Only
-values >=1 are valid. Default value is '2'.
-@item oacutoff
-@cindex array cutoff
-When displaying an array as struct field, display only the elements up to the
-@code{cutoff} index and display @code{@dots{}} after that. Value of @code{0}
-means no limit. This cutoff value is not used when directly displaying arrays
-content.
-@item omaps
-@cindex maps, of displayed values
-Flag indicating whether including mapping information when printing
-out mapped values.
-@end table
+@include poke-settings.texi
 
 @node vm command
 @section @code{.vm}
diff --git a/doc/settings-to-texi.pk b/doc/settings-to-texi.pk
new file mode 100644
index 00000000..94e716bf
--- /dev/null
+++ b/doc/settings-to-texi.pk
@@ -0,0 +1,42 @@
+/* Emit documentation for the poke settings in texinfo format in the
+   standard output.  */
+
+/* Copyright (C) 2022 Jose E. Marchesi */
+
+/* This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+print "@table @code";
+
+for (setting in pk_settings.entries)
+{
+  print "\n";
+  print "@item " + setting.name + "\n";
+
+  var normalized = "";
+  for (c in setting.description)
+    if (c == '{')
+      normalized += "@{";
+    else if (c == '}')
+      normalized += "@}";
+    else if (c == '@')
+      normalized += "@@";
+    else
+      normalized += c as string;
+
+  print normalized;
+}
+
+print "\n";
+print "@end table\n";
-- 
2.11.0