Re: Texinfo in Guile Scheme docstrings?

Tomas Volf <[email protected]> Sun, 16 Feb 2025 16:27:41 +0100
Newsgroups	gmane.lisp.guile.devel
Message-ID	<[email protected]>
Maxim Cournoyer <[email protected]> writes:

> 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 :-).

While the built-in ,d in the REPL does not process the Texinfo, some
third party tools do.  For example geiser-doc-symbol-at-point.  I think
we should modify the ,d to support it as well.

In my personal library, I wrote a script[0] to extract the documentation
strings into the manual[1].

So in my experience having the Texinfo in docstrings is nice.  Only
gripe I have with it is that (texinfo) module is bit limited, and
rejects a lot (for some value of "lot" :)) of valid texinfo.

Tomas

0: https://git.wolfsden.cz/guile-wolfsden/tree/build-aux/doc-snarf.scm
1: https://files.wolfsden.cz/manuals/guile-wolfsden/guile-wolfsden-0.0.7.html#Auto_002dgenerated-documentation

-- 
There are only two hard things in Computer Science:
cache invalidation, naming things and off-by-one errors.
signature.asc (application/pgp-signature, 853 B)