On 2/16/25 6:48 AM, Maxim Cournoyer wrote:
Hi Yuval,
Yuval Langer<yuval.lan...@gmail.com> 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))))
