Re: Some issues with guile

[Tomas Volf]

On 2024-04-26 03:05:51 -0400, Nikolaos Chatzikonstantinou wrote:
> Hello list,
>
> I want to talk about some issues I've encountered with Guile. I'll
> quickly summarize the points and I'll expand below.
>
> 1. Can't connect geiser from emacs to a remote REPL server unless
> versions match.
> 2. Documentation extraction sucks.
> 3. Programs/libraries that use Guile as an extension language are
> incompatible with one another.
>
> If anyone can help with these points I would appreciate it. Keep in
> mind that I am not a seasoned schemer nor intimately familiar with the
> GNU Guile manual and it is possible that I've misunderstood something.
>
> 1. The easiest OS to hack on Guile is Guix. I don't run Guix so I
> spinned a VM with it, where I installed guile-next for the
> bleeding-edge guile. I attempted to run `guile --listen` in the VM and
> `connect-to-guile` in the (Debian) host, but I'm getting errors, it's
> not working. I don't quite understand why. The errors seem to be
> related to version incompatibility, but I don't understand what if
> anything my host guile package has to do with the guest VM guile
> package.
>
> 2. There's an issue with documentating source code. The best system
> I've seen is Rust's, but sphinx and Doxygen work fine too. At the very
> least, a documentation system should have the following features:
>   i. document all language constructs
>   ii. markup (i.e. code blocks, links to other items)
>   iii. exportable
> Of course there can be more features, such as unit tests in
> documentation, but I don't consider them essential. I don't know what
> Guile does. I know there's `guild doc-snarf` and
> `(ice-9 documentation)` with docstrings, as well as the package
> documentá (.) These don't 
> work:
>   - `guild doc-snarf` does something clumsily ONLY with
> double-semicolon comments. Triple-semicolon file headers that
> explain the purpose of a module are ignored, for example. It's not
> clear what the utility of the output of this tool is.
>   - `object-documentation` from `(ice-9 documentation)` only seems to
> work with docstrings of functions, although it claims to work with
> macros too, suggesting that the `documentation` property should be
> set. But how? It's not explained. The info page on "Object
> Properties" makes it seem like this suffices: (set! (documentation
> my-function) "the docstring.")  but I can't get it to work like
> that. Docstrings cannot document files. Maybe they can document
> macros, variables, and modules at least?

What you want is:

(set-object-property! foo 'documentation "Contains a @code{'bar}.")

> But the docstring format is raw, there is no markup!

You can write them in whatever markup you want, I personally use texinfo format
(next version of geiser will be able to process and display it nicely).

>   - documentá in its page does not include an example of how it works!
> Not a line of code to explain to the user which documentation is
> extracted. I could not understand how to use it.
>
> 3. I use GNU GDB for debugging. Sometimes there's a desire to be able
> to interpret byte values in memory. GNU poke allows for this sort of
> thing. Both programs are very similar in how they behave, and in
> theory it should be possible to run poke commands from gdb, especially
> since there's libpoke for this exact purpose. However, this is not
> possible as far as I've been told, and the reason is that both libpoke
> and gdb load guile, and therefore, gdb cannot load libpoke in memory
> because of some issue with the Guile garbage collector! This is
> terribly disappointing. Can anyone clarify what is going on with this
> sort of thing? Workarounds so far include compiling gdb without guile
> support (everyone uses python for scripting in gdb anyway) or dumping
> byte ranges from gdb and examining them from the poke process
> separately.
>

--
There are only two hard things in Computer Science:
cache invalidation, naming things and off-by-one errors.


signature.asc
Description: PGP signature

Re: Some issues with guile

[Luis Felipe]

Hi Nikolaos,

El 26/04/24 a las 7:05, Nikolaos Chatzikonstantinou escribió:

2. Documentation extraction sucks.

[...]

   - documentá in its page does not include an example of how it works!
 Not a line of code to explain to the user which documentation is
 extracted. I could not understand how to use it.


Yeah, I didn't want to include how to document code in Documentá. 
Instead, I wanted to propose adding that documentation to Guile's 
documentation and link to it from Documentá. But I haven't made the time 
to write the proposed section.


Currently, Documentá can extract module documentation and procedure 
documentation. It also documents variables, record types, and macros 
exported by modules, but it simply lists them (record type fields are 
listed too), it doesn't extract any particular documentation added by 
human code writers. I haven't found, and in some cases investigated, a 
way to properly document variables, macros, record types and GOOPS 
clases using human-written documentation strings. But I want to have 
that too.


You can see examples of module and procedure documentation in 
Documentá's source 
(https://codeberg.org/luis-felipe/guile-documenta/src/branch/trunk/documenta). 
Note that for module documentation Documentá supports the conventional 
format


  ;;; Commentary:

  ;;; Your module documentation here ↓

  ;;; Code:

  ;;; Your code here ↓

Guile Scheme comments in the "Commentary" section are considered module 
documentation. You can use block comments too, the ones surrounded in #| 
... |#, instead of multiple line comments (see Documentá source code for 
examples).


Finally, better structuring, indexing and linking of generated API 
documentation are planned. I also want to explore exporting to Org format.


Hope that helps,


OpenPGP_0x0AB0D067012F08C3.asc
Description: OpenPGP public key


OpenPGP_signature
Description: OpenPGP digital signature

Some issues with guile

[Nikolaos Chatzikonstantinou]

Hello list,

I want to talk about some issues I've encountered with Guile. I'll
quickly summarize the points and I'll expand below.

1. Can't connect geiser from emacs to a remote REPL server unless
versions match.
2. Documentation extraction sucks.
3. Programs/libraries that use Guile as an extension language are
incompatible with one another.

If anyone can help with these points I would appreciate it. Keep in
mind that I am not a seasoned schemer nor intimately familiar with the
GNU Guile manual and it is possible that I've misunderstood something.

1. The easiest OS to hack on Guile is Guix. I don't run Guix so I
spinned a VM with it, where I installed guile-next for the
bleeding-edge guile. I attempted to run `guile --listen` in the VM and
`connect-to-guile` in the (Debian) host, but I'm getting errors, it's
not working. I don't quite understand why. The errors seem to be
related to version incompatibility, but I don't understand what if
anything my host guile package has to do with the guest VM guile
package.

2. There's an issue with documentating source code. The best system
I've seen is Rust's, but sphinx and Doxygen work fine too. At the very
least, a documentation system should have the following features:
  i. document all language constructs
  ii. markup (i.e. code blocks, links to other items)
  iii. exportable
Of course there can be more features, such as unit tests in
documentation, but I don't consider them essential. I don't know what
Guile does. I know there's `guild doc-snarf` and
`(ice-9 documentation)` with docstrings, as well as the package
documentá (.) These don't work:
  - `guild doc-snarf` does something clumsily ONLY with
double-semicolon comments. Triple-semicolon file headers that
explain the purpose of a module are ignored, for example. It's not
clear what the utility of the output of this tool is.
  - `object-documentation` from `(ice-9 documentation)` only seems to
work with docstrings of functions, although it claims to work with
macros too, suggesting that the `documentation` property should be
set. But how? It's not explained. The info page on "Object
Properties" makes it seem like this suffices: (set! (documentation
my-function) "the docstring.")  but I can't get it to work like
that. Docstrings cannot document files. Maybe they can document
macros, variables, and modules at least? But the docstring format
is raw, there is no markup!
  - documentá in its page does not include an example of how it works!
Not a line of code to explain to the user which documentation is
extracted. I could not understand how to use it.

3. I use GNU GDB for debugging. Sometimes there's a desire to be able
to interpret byte values in memory. GNU poke allows for this sort of
thing. Both programs are very similar in how they behave, and in
theory it should be possible to run poke commands from gdb, especially
since there's libpoke for this exact purpose. However, this is not
possible as far as I've been told, and the reason is that both libpoke
and gdb load guile, and therefore, gdb cannot load libpoke in memory
because of some issue with the Guile garbage collector! This is
terribly disappointing. Can anyone clarify what is going on with this
sort of thing? Workarounds so far include compiling gdb without guile
support (everyone uses python for scripting in gdb anyway) or dumping
byte ranges from gdb and examining them from the poke process
separately.