[gnutls-devel] Guile-GnuTLS | Example Echo Client/Server Contains Removed Functions (#16)

[Read-only notification of GnuTLS library development activities]

Skyler Ferris commented: https://gitlab.com/gnutls/guile/-/issues/16#note_1521480551

I started working on this. It's very "rough draft" right now, but [it shows my intentions](https://gitlab.com/skyvine/guile-gnutls/-/commit/c27a24ed36f6a681616a5250b8d95c923b86a0a8). I haven't used autotools before so I might need some help understanding how to modify those scripts. In the meantime, I added a phase to `guix.scm` so I could try it.

I want to be able to split this change across multiple commits without breaking the build on any individual commit. This is why the build phase checks if `main` is defined before calling it. Unfortunately, this does not work with the examples as-is, because some of them expect interactive input.

There are 2 competing concerns here. On one hand, we want the examples to be testable to make sure that people have accurate information. On the other hand, we want the examples to be easily understood by people who are unfamiliar with the GNUTLS API, and possibly new to TLS itself. This means that the examples should not only be readable, but also easy to modify for the purpose of exploring the library. I assume that the latter concern is the reason that some of the examples have interactive input.

The convention demonstrated in the WIP commit is for each example to define a `main` function which takes an `#:automated?` argument that defaults to false. This way if a person runs it without reading it fully (I know, but the reality is that people do that, particularly when testing an unfamiliar project for usability) then it will behave in the way that is most useful to them. The build system will pass `#:automated? #t`.

Accounting for both of these concerns does degrade the quality of the code in terms of maintainability and explorability. However, I think that if the code is written with these concerns in mind the impact can be minimized. In general, I would prefer additional cognitive load for testing rather than exploring. The tester is presumably better equipped to manage it than the explorer, who is in an unfamiliar environment.

I propose the following series of commits:

1. A set of commits which updates each example currently in `guile/examples` to use the `main #:automated?` convention.
2. A commit which updates autotools to run something equivalent to the build phase in the WIP commit.
3. A set of commits which moves each example from the manual into `guile/examples`.
4. Possibly, commits to add examples currently in `guile/examples` to the manual.

If this sounds good to you, I could send commits as I complete them or open a single merge request once everything is done, whatever works better on your end. I am working on this in my spare time, so it might take a while to complete it all.

-- 
Reply to this email directly or view it on GitLab: https://gitlab.com/gnutls/guile/-/issues/16#note_1521480551
You're receiving this email because of your account on gitlab.com.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.gnupg.org/pipermail/gnutls-devel/attachments/20230821/56222d0d/attachment.html>