On Mon, Apr 29, 2024 at 10:19 AM Dr. Arne Babenhauserheide
<arne_...@web.de> wrote:
>
> Hi Nikolaos,
>
> thank you for your patch!
>
> I only found a small nitpick:
>
> > +where the documentation of a module is included in texinfo format in
> > +@code{<Module documentation>} and Guile code follows after@code{Code:}.
>
> Maybe add a note that <Module documentation> can span multiple lines?
>
> Is there a space missing after "after"?
>
> Can you send an updated patch?
Hello, I updated the patch. (Re-added to guile-devel list.)
Regards,
Nikolaos Chatzikonstantinou
From c600f45bba95181952978068afdeb9dcf991f924 Mon Sep 17 00:00:00 2001
From: Nikolaos Chatzikonstantinou <nchatz...@gmail.com>
Date: Mon, 29 Apr 2024 08:38:33 -0400
Subject: [PATCH] doc: add example for module texinfo doc format
---
doc/ref/texinfo.texi | 23 ++++++++++++++++++++++-
1 file changed, 22 insertions(+), 1 deletion(-)
diff --git a/doc/ref/texinfo.texi b/doc/ref/texinfo.texi
index 64a866b23..77b4fb95f 100644
--- a/doc/ref/texinfo.texi
+++ b/doc/ref/texinfo.texi
@@ -472,11 +472,32 @@ Serialize the stexi @var{tree} into plain texinfo.
@node texinfo reflection
@subsection (texinfo reflection)
@subsubsection Overview
-Routines to generare @code{stexi} documentation for objects and modules.
+Routines to generate @code{stexi} documentation for objects and modules.
Note that in this context, an @dfn{object} is just a value associated
with a location. It has nothing to do with GOOPS.
+The convention for documenting Guile code is to include a
+three-semicolon comment block such as
+
+@example
+;;; Commentary:
+;;; The file or module documentation goes here.
+;;;
+;;; Use the GNU Texinfo (@pxref{Top,,, texinfo, The GNU Texinfo Manual})
+;;; documentation system. It allows for @emph{markup}, @LaTeX{},
+;;; inserting images, code examples like,
+;;; @example
+;;; (display "Hello world")
+;;; @print{} "Hello world"
+;;; @end example
+;;; and has many other features.
+;;; Code:
+@end example
+
+where the documentation of a module is included in GNU Texinfo format
+under @code{Commentary:} and Guile code follows after @code{Code:}.
+
@subsubsection Usage
@anchor{texinfo reflection module-stexi-documentation}@defun module-stexi-documentation sym-name [%docs-resolver] [#:docs-resolver]
Return documentation for the module named @var{sym-name}. The
--
2.39.2
