a cookbook

a cookbook

[Catonano]

[-- Attachment #1: Type: text/plain, Size: 310 bytes --]

In this discussion
https://lists.gnu.org/archive/html/guile-user/2022-02/msg00113.html

we hinted on the possibility of having a Guile Cookbook, along the lines of
the Guix Cookbook

Is there any interest/possibility to have such a cookbook hosted within the
Guile official documentation (as it is for Guix) ?

[-- Attachment #2: Type: text/html, Size: 513 bytes --]

Re: a cookbook

[Max Brieiev]

Yes, this would be very helpful.

In particular, it would be very helpful to have a step-by-step guide for
a sample app, like a basic HTTP server, which would cover the following
topics:

1. How do I set up the project from scratch?
2. What is recommended directory layout?
3. How do I manage project dependencies?
4. How do I build the project?

Re: a cookbook

[Olivier Dion via Developers list for Guile, the GNU extensibility library]

On Mon, 14 Feb 2022, Max Brieiev <max.brieiev@gmail.com> wrote:
> Yes, this would be very helpful.
>
> In particular, it would be very helpful to have a step-by-step guide for
> a sample app, like a basic HTTP server, which would cover the following
> topics:
>
> 1. How do I set up the project from scratch?
> 2. What is recommended directory layout?
> 3. How do I manage project dependencies?
> 4. How do I build the project?

I've started a small TexInfo manual for that.  I will try to share it by
the end of the week or this weekend.

-- 
Olivier Dion
Polymtl

Re: a cookbook

[Catonano]

[-- Attachment #1: Type: text/plain, Size: 294 bytes --]

Il giorno lun 14 feb 2022 alle ore 17:56 Olivier Dion via Developers list
for Guile, the GNU extensibility library <guile-


> I've started a small TexInfo manual for that.  I will try to share it by
> the end of the week or this weekend.
>
> Thank you, Olivier
>
> I'm looking forward to it
>

[-- Attachment #2: Type: text/html, Size: 564 bytes --]

Re: a cookbook

[Vijay Marupudi]

> Is there any interest/possibility to have such a cookbook hosted
> within the Guile official documentation (as it is for Guix) ?

I personally think that a Cookbook should be an independent effort, with
links from the Guile Manual if possible. This would lighten the load on
the maintainers, and allow for quicker collaboration.

To start, I think people should write Guile tutorials about things they
know about, license them using an open license, and let the community
know about the tutorials. Compiling these tutorials into a Cookbook
should be easy then.

Many tutorials exist out there, they need to found and listed. For e.g.,
here is a very detailed tutorial by Erik Edrosa on how to setup an Guile
autotools package.

https://erikedrosa.com/2017/10/29/guile-projects-with-autotools.html

Or snippets to capture stdout and stderr from a process from Arne
Babenhauserheide.

https://www.draketo.de/software/guile-capture-stdout-stderr.html

Finding and compiling lists of existing tutorials and snippets would be
a productive way to start on this effort.

I've personally started on this effort yesterday, writing about error
handling in Guile.

https://vijaymarupudi.com/blog/2022-02-13-error-handling-in-guile.html

I'd be happy to create a website compiling everything together, but the
hard part is writing and finding the tutorials.

~ Vijay

Re: a cookbook

[Catonano]

[-- Attachment #1: Type: text/plain, Size: 1548 bytes --]

Il giorno lun 14 feb 2022 alle ore 18:01 Vijay Marupudi <
vijay@vijaymarupudi.com> ha scritto:

> > Is there any interest/possibility to have such a cookbook hosted
> > within the Guile official documentation (as it is for Guix) ?
>
> I personally think that a Cookbook should be an independent effort, with
> links from the Guile Manual if possible. This would lighten the load on
> the maintainers, and allow for quicker collaboration.
>

but then the discoverability of the cookbook would be diminished 🙁





> I've personally started on this effort yesterday, writing about error
> handling in Guile.
>
> https://vijaymarupudi.com/blog/2022-02-13-error-handling-in-guile.html
>
> I'd be happy to create a website compiling everything together, but the
> hard part is writing and finding the tutorials.
>


First: thank you so much for this write up about the new exception
framework !

I couldn't come around and read it yet but this has been sorely missing
until now !

As for you creating a web site, I'd prefer such a website to be a
communitarian effort, rather than depend on a single person

Maybe a wiki on Gitlab could do and it could have several mantainers ?
I'd be happy to be one

This is a test by me
https://gitlab.com/humanitiesNerd/guilecookbook/-/wikis/read-a-file

I could add a page with a collection of the tutorials you indicated, better
yet if you would do that yourself 🙂

It's pretty dry now but it's also pretty young 🙂

Maybe it can grow, given some time 🙂

[-- Attachment #2: Type: text/html, Size: 2470 bytes --]

Re: a cookbook

[Neil Jerram]

On Wed, 16 Feb 2022 at 09:04, Catonano <catonano@gmail.com> wrote:
>
> Il giorno lun 14 feb 2022 alle ore 18:01 Vijay Marupudi <vijay@vijaymarupudi.com> ha scritto:
>>
>> > Is there any interest/possibility to have such a cookbook hosted
>> > within the Guile official documentation (as it is for Guix) ?
>>
>> I personally think that a Cookbook should be an independent effort, with
>> links from the Guile Manual if possible. This would lighten the load on
>> the maintainers, and allow for quicker collaboration.
>
>
> but then the discoverability of the cookbook would be diminished 🙁

Yes, agree that the resulting cookbook needs to be easily
discoverable.  Perhaps that means that if you install a guile-doc
package, it appears as a top-level Info item like Guile Reference
does.  Perhaps it doesn't need to be quite as specific as that.
(Although personally I really like doc being available locally, e.g.
in Info form, instead of always going online.)

But as you also say...

> [...]
>
> As for you creating a web site, I'd prefer such a website to be a communitarian effort, rather than depend on a single person
>
> Maybe a wiki on Gitlab could do and it could have several mantainers ?
> I'd be happy to be one

Yes, definitely feels right to crowd-source this, instead of having it
centralized in the core Guile repo.

It feels to me that with the right structure in place, people will
readily come and contribute the detailed material to it.  So it's
worth spending a little time to decide the right structure.

Best wishes,
    Neil

Re: a cookbook

[Catonano]

[-- Attachment #1: Type: text/plain, Size: 721 bytes --]

Il giorno mer 16 feb 2022 alle ore 10:54 Neil Jerram <neiljerram@gmail.com>
ha scritto:

>
>
>
> > As for you creating a web site, I'd prefer such a website to be a
> communitarian effort, rather than depend on a single person
> >
> > Maybe a wiki on Gitlab could do and it could have several mantainers ?
> > I'd be happy to be one
>
> Yes, definitely feels right to crowd-source this, instead of having it
> centralized in the core Guile repo.
>
> It feels to me that with the right structure in place, people will
> readily come and contribute the detailed material to it.  So it's
> worth spending a little time to decide the right structure.
>

Have you any suggestion about a structure you would deem appropriate ?

[-- Attachment #2: Type: text/html, Size: 1117 bytes --]

Re: a cookbook

[Neil Jerram]

On Wed, 16 Feb 2022 at 21:14, Catonano <catonano@gmail.com> wrote:
>
>
>
> Il giorno mer 16 feb 2022 alle ore 10:54 Neil Jerram <neiljerram@gmail.com> ha scritto:
>>
>>
>>
>>
>> > As for you creating a web site, I'd prefer such a website to be a communitarian effort, rather than depend on a single person
>> >
>> > Maybe a wiki on Gitlab could do and it could have several mantainers ?
>> > I'd be happy to be one
>>
>> Yes, definitely feels right to crowd-source this, instead of having it
>> centralized in the core Guile repo.
>>
>> It feels to me that with the right structure in place, people will
>> readily come and contribute the detailed material to it.  So it's
>> worth spending a little time to decide the right structure.
>
>
> Have you any suggestion about a structure you would deem appropriate ?

No, I want to let others lead on this.  (As Blake just reminded me, I
had a go at something like this several years ago, and it didn't work.
Also worry that I'd only disappoint, because of lack of my own
available time.)

Best wishes,
     Neil

Re: a cookbook

[Catonano]

[-- Attachment #1: Type: text/plain, Size: 445 bytes --]

Il giorno sab 19 feb 2022 alle ore 14:18 Neil Jerram <neiljerram@gmail.com>
ha scritto:

> Have you any suggestion about a structure you would deem appropriate ?
>
> No, I want to let others lead on this.  (As Blake just reminded me, I
> had a go at something like this several years ago, and it didn't work.
> Also worry that I'd only disappoint, because of lack of my own
> available time.)
>
> Best wishes,
>      Neil
>

Ok, thank you, Neil

[-- Attachment #2: Type: text/html, Size: 839 bytes --]

Re: a cookbook

[Olivier Dion via Developers list for Guile, the GNU extensibility library]

On Mon, 14 Feb 2022, Vijay Marupudi <vijay@vijaymarupudi.com> wrote:
>> Is there any interest/possibility to have such a cookbook hosted
>> within the Guile official documentation (as it is for Guix) ?

> I've personally started on this effort yesterday, writing about error
> handling in Guile.
>
> https://vijaymarupudi.com/blog/2022-02-13-error-handling-in-guile.html

Awesome blogpost.  Very clean and fun to read!  Is this generated with
static website generator for org-mode?

-- 
Olivier Dion
Polymtl

Re: a cookbook

[Vijay Marupudi]

> Awesome blogpost.  Very clean and fun to read!  Is this generated with
> static website generator for org-mode?

That's great to hear! Appreciate the feedback, I'm glad the writing
style is working, will try to maintain it.

The website is a static website that is implemented in Guile, but does
not use any static website generator library.

However, it does use Nectar, which is a markup library that allows you
to use Guile in the markup itself. I will write documentation for it
soon, and try to implement an Org-Mode converter (Markdown was recently
implemented). My goal is to use the library to supercharge the tutorial
and guide writing and viewing experience. Nectar will allow me to make a
very interactive and useful website, for which content can also be
transpiled into Texinfo, Markdown, Plain text, Org-Mode, or anything else
people would like.

My website was a dogfooding attempt, and it has worked well, so
hopefully more good things to come :)

Blog post source / Nectar sample:
https://gitlab.com/vijaymarupudi/vijaymarupudi.com/-/blob/master/content/2022-02-13-error-handling-in-guile.nct

Nectar: https://gitlab.com/vijaymarupudi/nectar

Website source code: https://gitlab.com/vijaymarupudi/vijaymarupudi.com

Re: a cookbook

[Catonano]

[-- Attachment #1: Type: text/plain, Size: 577 bytes --]

Hi,


> I've personally started on this effort yesterday, writing about error
> handling in Guile.
>
> https://vijaymarupudi.com/blog/2022-02-13-error-handling-in-guile.html
>
>
I've finally read your post

It's nice that it clears the distinction between old forms and new ones

I'd like to have continuable exceptions covered, though

Those are the main departure of Guile from more widespread exception
handling solutions and as far as I can tell something similar is available
only in Common Lisp so drawing experience/intuition from other languages is
more difficult/rare

[-- Attachment #2: Type: text/html, Size: 1070 bytes --]

Re: a cookbook

[Vijay Marupudi]

> I'd like to have continuable exceptions covered, though
>
> Those are the main departure of Guile from more widespread exception
> handling solutions and as far as I can tell something similar is available
> only in Common Lisp so drawing experience/intuition from other languages is
> more difficult/rare

Sure. I've added new text covering those as well. If you refresh the
page, it should appear:
https://vijaymarupudi.com/blog/2022-02-13-error-handling-in-guile.html

~ Vijay

Re: a cookbook

[dsmich]

[-- Attachment #1: Type: text/plain, Size: 884 bytes --]

> From: "Vijay Marupudi" 
> To: "Catonano", "guile-devel"
> Subject: Re: a cookbook

> > Is there any interest/possibility to have such a cookbook hosted
> > within the Guile official documentation (as it is for Guix) ?

> I personally think that a Cookbook should be an independent effort,
> with
> links from the Guile Manual if possible. This would lighten the load
> on
> the maintainers, and allow for quicker collaboration.

I found this interesting: https://diataxis.fr/

Classifies documentation into 4 types

Tutorials: Learning oriented
How-To Guides: Task oriented
Explanation: Understanding oriented
Reference: Information oriented

The Guile Manual is a Reference. Mainly a Reference. There are some
tutorial-like things in it, and some explanations, but not much.

It really would be good to have more non-reference documentation.

-Dale



[-- Attachment #2: Type: text/html, Size: 1078 bytes --]

Re: a cookbook

[Vijay Marupudi]

dsmich@roadrunner.com writes:

> The Guile Manual is a Reference. Mainly a Reference. There are some
> tutorial-like things in it, and some explanations, but not much.
>
> It really would be good to have more non-reference documentation.

I fully agree, if possible, under the Guile documentation would be
great. However, I was just trying to lighten the load on the
maintainers, who already have a lot to do.

~ Vijay

Re: a cookbook

[dsmich]

[-- Attachment #1: Type: text/plain, Size: 689 bytes --]

> From: "Vijay Marupudi" 
> To: "Catonano"
> Subject: Re: a cookbook

>> I'd like to have continuable exceptions covered, though
 >>
 >> Those are the main departure of Guile from more widespread
exception
 >> handling solutions and as far as I can tell something similar is
available
 >> only in Common Lisp so drawing experience/intuition from other
languages is
 >> more difficult/rare
 >
 >Sure. I've added new text covering those as well. If you refresh the
 >page, it should appear:
 >https://vijaymarupudi.com/blog/2022-02-13-error-handling-in-guile.html

This is *really* good. Pull in all the separate pieces and how they
fit together. Great job!

-Dale



[-- Attachment #2: Type: text/html, Size: 887 bytes --]

Re: a cookbook

[Vijay Marupudi]

> This is *really* good. Pull in all the separate pieces and how they
> fit together. Great job!

Thank you! More coming soon, hopefully :)

~ Vijay