From mboxrd@z Thu Jan 1 00:00:00 1970 From: Bengt Richter Subject: Re: extending the documentation of the Scheme API Date: Mon, 23 Dec 2019 03:44:47 -0800 Message-ID: <20191223114447.GA37723@PhantoNv4ArchGx.localdomain> References: <87sgleprp6.fsf@elephly.net> Reply-To: Bengt Richter Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:470:142:3::10]:51204) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ijM97-0006UL-Gy for guix-devel@gnu.org; Mon, 23 Dec 2019 06:45:11 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ijM93-0007Az-Vz for guix-devel@gnu.org; Mon, 23 Dec 2019 06:45:08 -0500 Received: from imta-36.everyone.net ([216.200.145.36]:44190 helo=imta-38.everyone.net) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1ijM93-00076W-AZ for guix-devel@gnu.org; Mon, 23 Dec 2019 06:45:05 -0500 Content-Disposition: inline In-Reply-To: <87sgleprp6.fsf@elephly.net> List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: Ricardo Wurmus Cc: Guix-devel Hi Ricardo, Guix On +2019-12-20 23:17:41 +0100, Ricardo Wurmus wrote: > Hi Guix, >=20 > we have lots of nice macros and procedures in Guix that aren=E2=80=99t > documented beyond their docstrings. >=20 > Should we snarf the docstrings and add them to the manual? >=20 > -- > Ricardo >=20 >=20 My 2 cents, if I may: I would _much_ rather be able to "snarf" dynamically from the command lin= e to stdout or -o file using appropriate parameters and options. Even something dead simple like gx-apropos: --8<---------------cut here---------------start------------->8--- #!/usr/bin/bash guile -c '(use-modules (ice-9 session))(apropos '"\"$*\""')' --8<---------------cut here---------------end--------------->8--- quickly gets me syntax essentials for default modules. (I have to do another variant to get this apropos to see rnrs bytevectors or other non-default modules). Yet another variant uses oop goops describ= e. I can view a manual and search it in emacs, but even so, sometimes I'd ra= ther insert the result of a command line invocation from within emacs. It only takes a few seconds to grep the whole guix git repo, a bit longer= for /gnu. Speaking of the latter, here is an alpha kludge to do approximately what ArchLinux's pacman -Qo does (find what package a given executable belongs= to). pacman -Qo $(which pacman) --8<---------------cut here---------------start------------->8--- /usr/bin/pacman is owned by pacman 5.2.1-1 --8<---------------cut here---------------end--------------->8--- my gx-Qo version (takes multiple args and shows pure vs not): gx-Qo g++ as readelf emacs lsblk less weston wayland gxQo --8<---------------cut here---------------start------------->8--- g++: gcc-9.1.0 as: binutils-2.32 readelf: binutils-2.32 emacs: emacs-26.3 lsblk: util-linux-2.34 less: less-530 weston: weston-6.0.1 wayland: (which: did not find) gx-Qo: (impure: '/home/bokr/bin/gx-Qo') --8<---------------cut here---------------end--------------->8--- When I get around to it I'll add a -a option to do which -a to report on all found. Also a -L option to report each link (possibly a chain) leading to to the executables. When/if I do, it will be an example of upgrading a single simple dynamic "documentation" producer vs upgrading a document per se. I much prefer dynamically on-the-fly-produced documentation of the state of my system -- like /proc stuff -- it's always up to date :) And emacs will let me escape with C-z to get to the command line when that is convenient (or necessary if pts doesn't do some tty thing). IMHO composing _independent_ functionalities ad-lib and powerfully is the best gift of the bash command line. ...|guix hash -|... allows me to use guix's internal default composition of sha256sum and bas= e32, but bash can already get at the former and IMHO it would enhance general composability if guix's base32 were packaged as external to guix = hash, so that bash could make use of the nix encoding also, that would be a plu= s for me e.g. maybe like ...|sha256sum|cut -d ' ' -f1|gx-base32|... It's a matter of what options you have to compose functionality. IMHO it would be good policy externalize hidden nuggets of shell-composable functionality whenever the nuggets don't need the package they come in to function. I think this should be viewed at the system architecture level so that the natural Chauvinism of an exciting project does not in effect create a walled garden that prohibits[1] cloning a simple (with simple system abi dependencies) internal wheel barrow=20 for use at home. [1]I know "prohibits" does not apply to extracting nuggets from FOSS, but the effort can be prohibitive, where the original developers of the nugget could have made it easy in many cases :-/ HTH in some way :) --=20 Regards, Bengt Richter