commit e0dd3c47423d36bdf3d77a52e597c9c4e20730d0
parent d0c0bc8932a8c66cf9990f3e9bafd248423a7c79
Author: lash <dev@holbrook.no>
Date: Mon, 1 May 2023 18:01:04 +0100
Add doc makefile, cache section to texinfo
Diffstat:
6 files changed, 82 insertions(+), 0 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,5 @@
examples/**/*.bin
examples/**/*.txt
**/.state
+build/
+doc/**/*html
diff --git a/Makefile b/Makefile
@@ -14,3 +14,6 @@ validate:
longmenu:
make -C examples/longmenu
+
+doc:
+ make -C doc
diff --git a/doc/Makefile b/doc/Makefile
@@ -0,0 +1,4 @@
+all: texinfo
+
+texinfo:
+ makeinfo --html -o build texinfo/index.texi
diff --git a/doc/texinfo/cache.texi b/doc/texinfo/cache.texi
@@ -0,0 +1,71 @@
+@node cache
+@chapter External data
+
+The @code{LOAD} instruction enables the client implementer to define external data retrieval and processing code.
+
+It can be used to:
+
+@itemize
+@item Query and store data
+@item Alter the menu execution flow
+@item Change language
+@end itemize
+
+
+@section The @code{LOAD} handler
+
+In the @emph{golang} code, the handler of the @code{LOAD} instruction is an implementation of the @code{resource.Resource} interface.
+
+It uses the method @code{resource.Resource.FuncFor} to return a function pointer of type @code{resource.EntryFunc} that can resolve the symbol.
+
+The @code{resource.Result} value that it returns has the following capabilities:
+
+@itemize
+@item Returned data payload (can be empty).
+@item A client-defined status code.
+@item A list of client-defined signal flags to @emph{set}.
+@item A list of client-defined signal flags to @emph{unset}.
+@end itemize
+
+
+@section Size limits
+
+@code{LOAD} instructions include a size parameter.
+
+This indicates the maximum byte size of the result that will be allowed.
+
+If the returned data payload exceeds this size, execution will terminate.
+
+
+@subsection "Sink" symbols
+
+A sink is a symbol loaded with @code{size} parameter @code{0}.
+
+This allows the contents to expand to all remaining available space when rendering a template. See @ref{dynamic_templates, Dynamic templates} for details.
+
+
+@section Scope
+
+The result data payload is stored under the symbol key for which it was loaded. It is kept in the cache until execution ascends from the execution stack level in which it was loaded.
+
+Consider the symbol @code{foo} loaded at node @file{root/one/two}. The symbol will still remain available in cache for e.g. node @file{root/one/two/three}, but will be freed when entering @file{root/one}.
+
+
+@subsection Duplicate @code{LOAD}
+
+If a @code{LOAD} statement with the same symbol is issued twice within the same @emph{scope}, it will fail and execution will terminate.
+
+If a @code{LOAD} statement with the same symbol is issued twice in the same @emph{node}, the latter will be ignored.
+
+For example, if @code{LOAD} is called on node @file{foo/bar}, then execution descends to @file{foo/bar/baz} before returning to @file{foo/bar}, the second time the @code{LOAD} statement is encountered in @file{foo/bar} will have no effect.
+
+However, if @code{LOAD} is called on node @file{foo/bar/baz}, then execution ascends to @file{foo/bar} before returning to @file{foo/bar/baz}, the @code{LOAD} will be executed again.
+
+
+@section Refreshing cache contents
+
+The @code{RELOAD} instruction will trigger the @code{LOAD} handler again. The @code{RELOAD} instruction is bound to the same size constraint as the initial @code{LOAD}.
+
+It is not possible for the handler code to distinguish between a @code{LOAD} and a @code{RELOAD} instruction.
+
+Note that using @code{RELOAD} when rendering multi-page menus can have unpredictable consequences for the lateral navigation state.
diff --git a/doc/texinfo/index.texi b/doc/texinfo/index.texi
@@ -28,5 +28,6 @@ Released 2023 under AGPL3
@include signals.texi
@include instructions.texi
@include navigation.texi
+@include cache.texi
@include render.texi
@include cookbook.texi
diff --git a/doc/texinfo/render.texi b/doc/texinfo/render.texi
@@ -6,6 +6,7 @@ Every node whose bytecode includes a @code{HALT} statement @strong{MUST} define
Templates may be either static or dynamic.
+@anchor{dynamic_templates}
@section Dynamic templates
Using placeholders, the content behind @code{MAP} calls in the current executing node may be embedded in the template.
