[-- 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 --]
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?
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
> 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
[-- 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 --]
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
[-- 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 --]
[-- 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 --]
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
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
[-- 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 --]
> 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
[-- 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 --]
> 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
[-- 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 --]
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
> This is *really* good. Pull in all the separate pieces and how they
> fit together. Great job!
Thank you! More coming soon, hopefully :)
~ Vijay
[-- 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 --]