[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[COMMITTED] doc: generate settings documentation from poke
From: |
Jose E. Marchesi |
Subject: |
[COMMITTED] doc: generate settings documentation from poke |
Date: |
Mon, 17 Jan 2022 14:22:58 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [COMMITTED] doc: generate settings documentation from poke,
Jose E. Marchesi <=