From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.lisp.guile.user Subject: Re: timestamp Date: Sat, 12 Feb 2022 19:32:26 +0200 Message-ID: <8335kornx1.fsf@gnu.org> References: <5cae853e6252bb3e38b1a20ff9ea960c1756c68c.camel@riseup.net> <9d45b2d6c007a8e9ca1e0656deed190f1181e035.camel@planete-kraus.eu> <098bbd5f1c81414521015479b7e2b17d8809f1bd.camel@riseup.net> <874k54tia0.fsf@elephly.net> <880d7dec038821cbba9c3963ff8bb667f68e7e4f.camel@riseup.net> <87zgmwry5u.fsf@elephly.net> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="17227"; mail-complaints-to="usenet@ciao.gmane.io" Cc: guile-user@gnu.org To: Ricardo Wurmus Original-X-From: guile-user-bounces+guile-user=m.gmane-mx.org@gnu.org Sat Feb 12 18:32:47 2022 Return-path: Envelope-to: guile-user@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nIwGN-0004KE-5a for guile-user@m.gmane-mx.org; Sat, 12 Feb 2022 18:32:47 +0100 Original-Received: from localhost ([::1]:41806 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nIwGM-0006d8-6x for guile-user@m.gmane-mx.org; Sat, 12 Feb 2022 12:32:46 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:39766) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nIwG9-0006ck-5J for guile-user@gnu.org; Sat, 12 Feb 2022 12:32:33 -0500 Original-Received: from [2001:470:142:3::e] (port=45430 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nIwG8-00059q-Pg; Sat, 12 Feb 2022 12:32:32 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=Q7ERiMgkLpNP2DsBJkKaYaDmhlDQw0i4+7dT+Of7rhw=; b=JlLrk73VVvhtJt/V4HWi iI0bOE5OU1dU34CEJ+raP3zv35jkxGQSvBb+7nI230soYhkl3C+cNsvDGwsZlhOILJRkIAAw8ykQp BWtMttz/jQ3ZjRahf8zXS7ICfbYIeAXuUan8hr1qvvsXfDTCVyFtczT0RKuhWkzo9p6NM1j6u8gif TQ1Wog7a3fdibVoCDMMZHR2o7azHhf7Iilf37hVksAfYB1+Z5g+HaQwPUo5AWqJEDqntU6uwzWYcZ wDYewWF1pWy8BiLfV3oHsyHHKSUrAHKKOPA/34mCmiUvElRkLVBC/rKWQHUV4S/xIzur6yJptIUAF RTmcpdA+a/kuuA==; Original-Received: from [87.69.77.57] (port=2700 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nIwG7-0004rU-Tk; Sat, 12 Feb 2022 12:32:32 -0500 In-Reply-To: <87zgmwry5u.fsf@elephly.net> (message from Ricardo Wurmus on Sat, 12 Feb 2022 14:49:20 +0100) X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: General Guile related discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-user-bounces+guile-user=m.gmane-mx.org@gnu.org Original-Sender: "guile-user" Xref: news.gmane.io gmane.lisp.guile.user:18098 Archived-At: > From: Ricardo Wurmus > Date: Sat, 12 Feb 2022 14:49:20 +0100 > Cc: guile-user@gnu.org > > > The argument of lack of examples in the Guile/Guix documentation has > > been made several times now, or at least, I've seen it being made > > several times > > The Guix documentation contains examples, but it’s already very long and > intimidating, so we started the Cookbook for more extensive tutorials > and examples. > > It hasn’t seen as much uptake by contributors as I hoped, but it’s there > and can be extended with more examples, big and small. I don't think just adding examples will cut it, although it will certainly help. My take of the issue is that the Guile reference manual is little more than the collection of the doc strings of the various Guile APIs. The doc strings are by their very nature quite terse and lack the "glue": the text which will explain the relative merits and demerits of each API wrt the other, the factors to consider when deciding which APIs to use, etc. It also doesn't make it easy to have helpful cross-references. Moreover, adding examples to the doc strings will have a disadvantage: it will increase the memory footprint of running Guile applications. Which is why I think the effort should be in the direction of extending the parts of the manual that aren't produced from the doc strings, but instead are written by humans to help other humans.