Re: Texinfo in Guile Scheme docstrings?

    On 2/16/25 6:48 AM, Maxim Cournoyer wrote:

    Hi Yuval,

    Yuval Langer<[email protected]> writes:

>     Hi,
>
>     I am writing docstrings to guile-srfi-189 currently[1] and looking for
>     good docstring style practices (that's another topic for another
>     thread).
>
>     I have noticed that there are some modules with Texinfo markup in
>     their docstrings, but I haven't found these markups being used in any
>     meaningful way.  I looked up two docstrings inside the Guile manual,
>     but couldn't find it there, so these docstrings are not used to
>     de-duplicate documentation.  The two I've searched are (srfi srfi-1)'s
>     assoc and (ice-9 popen)'s open-pipe*.
>
>     Someone had suggested the `guild doc-snarf` command, but it doesn't
>     output any of the docstrings.  What I did notice is that the text in
>     the docstrings defined in the /libguile/ C files can be found in the
>     Guile manual.  There is a tool called `guile-snarf` for the C code
>     docstrings, but that doesn't explain the Guile Scheme docstrings.
>
>     I am extremely confused.  Why have Texinfo in the docstrings of the
>     Scheme source when the docstrings defined in the C files are used?
>     Are there plans for developing tools that will display docstring in a
>     more intelligent way using those markups, like in the interactive
>     environment, or maybe assist in navigating the documentation?
    Sorry for not being helpful, but I've asked myself these questions
    before, and would also like to know the answer.  I assume there was a
    plan to render some of the the Texinfo markup in the interactive
    environment, but that's speculation :-).

    Did you try digging the git history and or guile-devel historical
    messages that could touch that topic?

I'm not sure of the context (C vs Scheme) but for Scheme I've been using
an emacs minor mode I wrote.  With this you document your procedure as
texinfo in comments, then hit C-c C-t d and formatted text is inserted
into your procedure.  See an example below.  The reference is:

https://github.com/mwette/guile-contrib/blob/main/scheme-texidoc.el

The scheme-texinfo minor mode code is not perfect, but usually works for me.

;; @deffn {Procedure} make-lalr-parser mach [options] => parser
;; Generate a procedure for parsing a language, where @var{mach} is
;; a machine generated by @code{make-lalr-machine}.
;; This generates a procedure that takes one argument, a lexical analyzer:
;; @example
;; (parser lexical-analyzer #:debug #t)
;; @end example
;; @noindent
;; and is used as
;; @example
;; (define xyz-parse (make-lalr-parser xyz-mach))
;; (with-input-from-file "sourcefile.xyz"
;;   (lambda () (xyz-parse (gen-lexer))))
;; @end example
;; @noindent
;; The generated parser is reentrant.  Options are:
;; @table @code
;; @item #:skip-if-unexp
;; This is a list of tokens to skip if not expected.  It is used
;; to allow comments to be skipped.  The default is @code{'()}.
;; @item #:interactive
;; If @code{#t}, this tells the parser that this is being called
;; interactively, so that the token @code{$end} is not expected.
;; The default value is @code{#f}.
;; @item #:env
;; Use the passed environment to the parser actions provided in the
;; specification.  This can be a module (e.g., @code{(current-module)}
;; or an environment (e.g., @code{(interaction-environment)}).   The
;; default is to use @code{(current-module)}; that is, the module in which
;; this procedure is being executed.
;; @end table
;; @noindent
;; @end deffn
(define* (make-lalr-parser mach
			   #:key
			   (skip-if-unexp '())
			   interactive
			   env)
   "- Procedure: make-lalr-parser mach [options] => parser
      Generate a procedure for parsing a language, where MACH is a
      machine generated by 'make-lalr-machine'.  This generates a
      procedure that takes one argument, a lexical analyzer:
           (parser lexical-analyzer #:debug #t)
      and is used as
           (define xyz-parse (make-lalr-parser xyz-mach))
           (with-input-from-file \"sourcefile.xyz\"
             (lambda () (xyz-parse (gen-lexer))))
      The generated parser is reentrant.  Options are:
      '#:skip-if-unexp'
           This is a list of tokens to skip if not expected.  It is used
           to allow comments to be skipped.  The default is ''()'.
      '#:interactive'
           If '#t', this tells the parser that this is being called
           interactively, so that the token '$end' is not expected.  The
           default value is '#f'.
      '#:env'
           Use the passed environment to the parser actions provided in
           the specification.  This can be a module (e.g.,
           '(current-module)' or an environment (e.g.,
           '(interaction-environment)').  The default is to use
           '(current-module)'; that is, the module in which this
           procedure is being executed."


   (let* ((mtab (assq-ref mach 'mtab))
	 (siu (map (lambda (n) (assoc-ref mtab n)) skip-if-unexp)))
     (if (number? (caar (vector-ref (assq-ref mach 'pat-v) 0)))
	;; hashed:
	(make-lalr-parser/num mach
			      #:skip-if-unexp siu
			      #:interactive interactive
			      #:env env)
	;; not hashed:
	(make-lalr-parser/sym mach
			      #:skip-if-unexp siu
			      #:interactive interactive
			      #:env env))))